| No matter what programming or scripting language you use, comments are and always will be an integral part of code writing. However, honestly it is often the most abused activities as well. Writing no comment is bad, so is writing too much! There's always a certain deal of practice required when putting forward your comment. |  |
1. Focus on readability of code: When writing code for a program, it's easy to fix all of the bugs and have it compile correctly, however making it easy for others to read is hard but very essential.
2. Don't write what code is doing: Leave the code to explain itself by giving class, variable and method meaningful name.
3. Always write why you are writing the code: Critical in order to identify any bug or behavior that comes accompanying the changing business environment.
4. Follow javadoc comment style: When writing core libraries to be used by different projects, it is advisable to document all assumptions and preconditions for using your API.
5. Include JIRA Number and description on comment: Gives a clear idea why a particular code was added and whether an issue that has crept up is because of that piece of code.
6. Make your comment as short as possible: Trust us, noone likes or has enough time to read longer comments.
7. No need to mention your name, employee id, your department etc in a comment:Those who wish to know can get the required info from the commit data.
8. Put comment while committing code in source control repository: People must know why you are adding a certain piece of code. Also include JIRA or QC number.
9. Include standards/information for upcoming developers in the beginning of your class as comment: Alerts that any new fields addition in this class must implement the same for future correspondence.
10. Give your code to a fellow developer to understand: Giving your code to a fellow developer to review the same and ask how much of it he understands is a healthy process.
