In previous article we have covered coding best practice for Naming conventions and I this article we will cover the best practice guidance for writing code comments.
- Comments should be used to describe the intent, algorithmic overview, and logical flow.
- Provide comments so that someone other than the original developer can understand the behavior and purpose of the code.
- As a best practice, most code has comments reflecting the developer’s intent and approach for the code.
- Use comments liberally.
- Include comments that indicate who made the changes.
- when the changes were made,
- Why the changes were added.
- What the changes you do.
- Comments are particularly beneficial when multiple parties are involved in modifying and maintaining code.
Developers should follow the following guidelines for writing code comments:
- Do not use comments that repeat the code.
- Do not use multi-line syntax, /* … */, for comments. Single-line syntax, // …, is preferred, even when a comment spans multiple lines.
public int getSum()
// This comment spans multiple
// lines because it has
// a lot to say. The use of
// multi-line syntax is
// not allowed.
- Do not place comments at the end of a line, unless the comment is very short. In most cases, comments should be placed above the code.
public class ArrayList
int count; // -1 indicates uninitialized array
- Remove TODO comments well in advance of a release.
// TODO: The TODO comments should start with TODO.
Comments should not include:
- Version or layer references
- Bug numbers – unless it is a workaround, or unless the code could appear inappropriate if you didn’t know that it was for a bug fix.
- Politically or culturally sensitive phrases