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.
  • One very good practice about code commenting yet ignored by developers is adding code comments in JavaScript, HTML and CSS files. Note that comments in these type of files can be added as shown below:

    HTML comment :
    JavaScript comment : /*This is JavaScript 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.

Related Posts

Best Practicies for adding code comments admin Core Java
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...
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 <a href="http://www.javaexperience.com/code-review-checklist/" title="Java Code Review Checklist">best practices</a> for adding comments in code are: <ul> <li> Our first approach should be to <strong>reduce the use of code comments</strong>. 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 <a href="http://www.javaexperience.com/generate-jdk-style-javadoc-documentation-for-java-application/" title="Generate JDK style javadoc documentation for Java application">part of javadoc</a> but we shall touch how to write javadoc shortly. </li> <li> 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 <strong>get the context of code</strong>. If the fellow developers do understand the context of code, they can very well make out the purpose of code. </li> <li> 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 <strong>javadoc documentation helps those API users</strong> 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 <a href="http://www.javaexperience.com/generate-jdk-style-javadoc-documentation-for-java-application/" title="Generate JDK style javadoc documentation for Java application">generate HTML based documentation</a> 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. </li> <li> One very good practice about code commenting yet ignored by developers is <strong>adding code comments in JavaScript, HTML and CSS</strong> files. Note that comments in these type of files can be added as shown below: <blockquote>HTML comment : <!-- I am an HTML comment --> JavaScript comment : /*This is JavaScript comment*/ CSS comment : /* This is CSS comment */ <a href="http://www.javaexperience.com/java-ee-adding-jsp-comments/" title="Adding JSP Comments">JSP Comment</a> : <%-- Sample JSP Comment --%> </blockquote> </li> <li> A commonly seen code comment in code shipped as open source is addition of <strong>copyright statements at the top</strong> 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. </li> <li> Another common nuisance regarding code comments is <strong>proper indentation</strong>. 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. </li> </ul>
Difference between Hashtable, Collections.synchronizedMap and ConcurrentHashMap
Multiple inheritance in Java
The following two tabs change content below.
I run this blog with lots of passion. In this website, you will find tutorials on Core Java, Spring, Struts, Web Applications, Portals and Database. Please support me and the website by sharing the posts on your facebook / twitter. You can tap the share button at the top of each post. Thanks for the support.

Comments

comments