Best Practicies for adding code comments
A lot has been written about code comments as it is a part of every programming language. But still developers don’t understand the proper tips and tricks for adding code comments. If followed properly adding code comments can really improve the productivity of everyone. Anyone reading the code written by fellow developers can really get an insight of logic written for a job.
The best use of code comments come in the maintenance phase of the application. Developers write code comments for purpose of code, copyright, bug reference and author. But still many developers mess with code comments which results is poor code readability.
Some of the best practices for adding comments in code are:
- Our first approach should be to reduce the use of code comments. Try to make the code self explanatory by using proper variable, method and class names. When using a method name as calculateBreakPower is best and we shouldn’t be using method name as calculate and then adding an inline comment “calculates break power”. Though some people tend to use such short comments as part of javadoc but we shall touch how to write javadoc shortly.
- Add comments for exceptional and complex code. A very good example of adding code comments is when a piece of code is performing a task based on user agent (IE/FireFox/Chrome/Safari). In such a case, the code tends to become complex and adding a line of comment about what is being done can really help other developers get the context of code. If the fellow developers do understand the context of code, they can very well make out the purpose of code.
- The purpose of javadoc is for other users who don’t have access to your source code. Such developers could be using the API exposed by you from class files. In such a case providing javadoc documentation helps those API users to understand the arguments, exceptions and return type of the methods. In fact there is a tool named javadoc which is shipped with JDK and can be used to generate HTML based documentation for the code. But if the application is for in-house use only then one can skip adding javadoc comments. Most of the developers don’t like javadoc but their importance is highlighted when you are developing a project which will be consumed by others as API.
HTML comment :
CSS comment : /* This is CSS comment */
JSP Comment : <%-- Sample JSP Comment --%>
- A commonly seen code comment in code shipped as open source is addition of copyright statements at the top of each source code file. If any body else the employees of your organization is going to view the source code then it is highly recommended to add copy right statements at the top of all source code files. This tells the viewers about their rights to use and edit the source code.
- Another common nuisance regarding code comments is proper indentation. Usually developers give more importance to the code they are writing and hence add proper indentation to code but don’t provide indentation to comments. Adding comments at proper place for better readability is the key for good code comments. If not properly readable, code comments loose their purpose.