1.05 Code comments

by

Aim: To learn about comments and how to use them.

Topics covered:

  • What are comments?
  • Why do we use comments?
  • How do we use comments?

Comments

Comments are sections of human readable text, that can be found in code. The purpose of comments is to increase the readability of code. They can also help with the construction of code and can be used to generate certain types of documentation.

Comments often come as single line comments or block comments. Following are some examples in different languages…

Java

// This is a single line comment

/*
This is a block comment.
It can span multiple lines.
*/

/* it can also be used within one line */

PHP

<?php
// This is a single line comment

# This is another form of single line comment

/*
This is a block comment.
It can span multiple lines.
*/

/* it can also be used within one line */
?>

VB.net

' This is a single line comment


' VB doesn't have a block comment
' so we just add a ' at the beginning
' of each line if we need to.

As you can see, single line comments come with a symbol (or symbols) at the beginning of the comment, and they are finished at the end of the line. Block comments aren’t supported in all languages, but have a set of symbols at the beginning and end of the block, this could be contained in one line or span many lines.

Commenting policy

A commenting policy may seem like overkill at first sight, but commenting is something that coders often naturally avoid. I have heard (and perhaps occasionally used) a number of excuses for not adding comments including: –

  • “It’s so simple it doesn’t need comments.”
  • “I’ll write the comments in later.”
  • “I don’t want anyone else touching it and I know what it does.”
  • “Nobody else updates the comments so they’ll just get out of date.”

There are occasions when some of these may be true, but too often they are excuses that don’t stand up to scrutiny. A commenting policy will avoid many difficulties further on in the life span of the project.

I strongly suggest that comments are always used to describe: –

  • Complex code
  • Code that is unusual in some way
  • Code that may appear to do one thing, but actually does another
  • Code that may have unexpected side-effects

In addition it is also useful to add comments to functions and variables, so they can be used without having to delve into the code of the function or see where the variable is used, to discover how to use them.

Commenting/documentation tools

When considering our commenting policy, we should also think about whether we are going to document our code with a documentation tool. These are tools that look through our code, extract comments and build up a set of documentation using them. They often require that comments be written in a particular way, so this is good to consider ahead of the project.

Problems with comments

Comments are a wonderful thing, when maintained and used correctly. Unfortunately comments can be more of a hindrance than a help when they are not well maintained. If a comment tells the coder incorrect information, then (for example) while trying to use a function or fix a bug with it, the coder may add bugs to the code, or take much longer to complete the task.

Bad comments include: –

  • Comments that are incorrect to start with
  • Comments that are ambiguous, or badly worded
  • Comments that have become out-of-date over time and have not been updated

In my experience the first of these points is very unusual, and the last is easily avoided, but so often is not. The commenting policy, should mention the maintenance of comments. If applicable, also include comment checking in your code review process.

In my opinion no comment is better than a bad comment, but good comments can improve productivity and quality significantly.

Feedback on 1.05 Code comments

If you have any questions or suggestions relating to this article or any other then please fill in our feedback form and let us know what you think.