Please let me know if there any problem for adding the developer comments in SAIL . I heard that its against the best practice.
It would be nice if would be nice if some one could provide me what are the best practice in Developer comments
Discussion posts and replies are publicly visible
Part of our best practices are to use comments to add JIRA story numbers, the name of developer, and changes made to the top of the code file, and then another comment adjacent to changed code to keep a rolling change log within Appian code objects, specifically SAIL interfaces and Expression Rules.
We also have a large annotation field on each PM which also serves as a change log.
Self-commenting code is a myth designed to make people feel good about not commenting their code. You should have clean elegant code with meaningful variable names such that you don't need to comment what a particular piece of logic does, but you still comment WHY you're doing it or even WHY you're doing it this way.
e.g. I see when there's anything after the third decimal place, you always round up, but WHY do you always round up? Because this module is for converting foreign currency into USD, and we need to make sure we always have AT LEAST enough USD down to the cent to cover the full amount of all the foreign currency. We'd rather overpay by up to a penny than not have enough.
This was part of the standard practice we had in place when I was a Mainframe COBOL developer: a 'Header' section that contained details of the Author/Developer of the code and any subsequent changes, along with the relevant Change Reference so that there was traceability of code changes to authorise requirements. And then, inline with the code, anything that needed to be called out to explain the what and/or the why, whatever it takes to reduce the friction that comes with changing someone else's code.