Code Comment

Introduction

Code Comment is the second pillar to a readable and maintainable code (first being good naming conventions). Mostly people do not pay much attention to comments when they start coding and later it grows big enough to force them to not pay attention and fix it. They may end up investing more time in putting up the right comments at right places.

There may be reasons to not use comments but believe me there are always more reasons to comment your code properly. Any time is a right time to add comments and adding comment is must be a continuous process. Even if you add a line of code in an existing huge file, you must write down the purpose of that line.

Imagine a scenario where you added a code as below:

If someone else reads this code or tries to maintain it later, it would be tough to understand the business logic and the next thing, he would be looking around for you.

No matter if it is source file, XML, properties, script file etc, we should always add comments to each of these files.

Type of comments in Java

Java Doc comments

  • Enclosed within /** */
  • Copied by the JavaDoc tool and processed to make it available for the Java Docs.
  • Also identified and processed by the popular IDEs, when you hover mouse on the usage of the class or method, it shows the complete comment as tool tip.

Block comments

  • Enclosed within /* */
  • It contains information about the particular block of the code and what it does. This can also be written as a method level comment of a concrete implementation.
  • We mostly need to focus on such comments. The more block comments we have, the easier it would be to maintain the code in future.

In-line comments

  • These are generally single line comments and should not be lengthy statements.
  • These comments start with //
  • Example: // Initialize a new array

What qualifies for a Java Doc comment?

Most of the time we are developing APIs and the APIs are to be consumed either by us or other teams or a wider audience who are our clients. How will a consumer know the functionality of an API, he mostly will refer the API documentation. A major part of the API documentation is the API level comments as javadoc tool uses it to generate the API documentation and I am sure so is the case with other languages.

What should be added to the API comments?

  • The APIs are mostly written as interfaces and it only contains method declarations. As the file size is not too big, it is always possible to add more comments in this file.
  • The comments in this file would be at two levels, Interface Level and Method(API) Level. These are the JavaDoc comments which will be processed by the javadoc tool.

The comments at interface level should contain the following:

  • a detailed description of the purpose of this interface,
  • @version for the version of the API with date created or updated,
  • @since for the version when it was introduced,
  • @author for the author name / email
  • @see for referring important custom classes and methods used in this API

The comments at method(API) level should contain the following:

  • a detailed explanation of the functionality of the API
  • all possible behaviour of the API based on the various user invocation
  • an example code to showcase a possible usage of the API enclosed with the pre tag or the code tag

The Other type of comments like the block comments and the in-line comments are to be added in the concrete(implemented) classes.

Few tips which can always prove to be helpful

  • A useful metric to measure code is LOC (Lines of Code). Ideally there should be around 30 lines of comments in a 100 line code.
  • Ideally a method should have 80 – 100 lines of code and 30 lines of comments.
  • Comments are not fancy stories, they have to be precise and they should convey the purpose.
  • While fixing a bug, make sure that the code fix you add should start and end with a comment with bug number or issue number.
  • Comments should be updated every time there is a change in the API, business logic or any other piece.

Stay connected and stay Subscribed