How To Write Good Code Comments
Uncovering the characteristics of what is considered, good or bad comments
Table of Contents
Today we will be taking a look into the comprehensive subject of code comments. Specifically uncovering the characteristics of what is considered, good or bad comments. In addition, we will discuss the two main types and the general rules that applies to each.
The overall idea behind comments
Code comments should be considered an important tool that brings clarity to otherwise un-clear or abstract information. Comments gives the designer a chance to capture the thoughts and ideas that leaded to their decisions. They provide the users of a system with the information they need, to make use of a given interface.
Comments also gives developers better intuition about certain implementations or an entire systems inner workings. Most importantly, comments makes the un-obvious, obvious. To take a quote from the great book, A Philosophy of Software Design by John Ousterhout.
The overall idea behind comments is to capture information that was in the mind of the designer but couldn’t be represented in code. – A Philosophy of Software Design
The two main types of comments
There’s different types of comments, but for our purposes we’ll just be looking at interface and implementation comments. Each of these requires a slightly altered perspective to write properly. Depending on the type, our intentions needs to change as the essence of the information we need to reveal differs. Let’s take a look at them in more detail.
Interface comments
By interface comments, we are not referring to the same interfaces that are used in the world of object oriented programming. Instead, function declarations such as the name and parameters, is an interface that will be used by some client. The comments associated with these declarations, are considered interface comments.
These types of comments should provide enough information to the client, so that they can make use of the interface without needing to explore the encapsulated code. Most languages uses these types of comments to generate documentation with tools such as Doxygen, phpDox and jsdoc, just to name a few.
Implementation comments
Comments found in the body of a function, class or script is considered implementation comments. Generally, the goal of these comments is to explain at a higher level, what the code is trying to do or what the designers intentions where. This gives us a nice overview of the inner workings of code block and allows us to critique it’s actions.
They can help point out bug workarounds, potential issues, or cryptic pieces of code. We usually write implementation comments when dealing with code of greater complexity, as simpler blocks of code rarely needs any additional clarification. They do however require some common sense to write well.
The two main characteristics of bad comments
They repeat the code
Comments that closely represents their related interface or implementation, for the most part, provides no real value. These types of comments basically just repeats the code itself, and does not give any additional information about the related interface or implementation.
In the following example we have a PHP class named Currency that contains a list of currency codes.
It has an opening comment that basically just repeats the class declaration and gives no further information. A better comment would have been something like: Holds all official ISO 4217 currency codes as constants (e.g, Currency::USD).
The revised comment provides us with the details we need to actually make use of the class. It reveals the currency code standards and how we might access them. Most importantly, we can use the class without having to look at the encapsulated code.
<?php
/**
* Class Currency.
*/
class Currency
{
const AFN = '971';
const EUR = '978';
// ...
}
?>
They leave us with questions
Comments can leave us with a lot questions. Forcing us to spend time exploring code bases or online forums looking for examples. The designer of the related code, never took the time to clarify things or believed these details to be obvious.
As an example, we have a PHP function named fitimage and it takes in 4 arguments, none of witch has been commented on. The 4 arguments are $image (int), $x (double), $y (double) and $optlist (string). The associated interface comment reads as follows: Place an image or template on the page, subject to various options.
<?php
/**
* Place an image
on the page, subject to various options.
*
* @param int $image
* @param double $x
* @param double $y
* @param string $optlist
*/
function fit_image($image, $x, $y, $optlist) {}
?>
This comment leaves us with a lot of questions, such as:
- Why is the image argument an integer, do I need to preload the image?
- Where is the origin of
xandy, top left, bottom left…? - If
xandyare doubles, then what unit type should I use to position my image, pixels? - Where can I find the available string options for optlist, and how would I use multiple options, do I separate them with a special character?
- These are just some of the questions that came to mind. Comments should make critical details like these clear by answering the what, and why of things.
Conclusion
Interface comments provides clients with the information they need to make use of an interface. Implementation comments should try to explain what the code is doing, not how it’s doing it. But generally, all comments should attempt to make the things that are not obvious, clear.
We as developers must recognize and appreciate the power of code comments and should take better care of writing them, for the benefits of ourselves and others. If you would like to learn more about writing good comments, you can take a look at the aforementioned book: A Philosophy of Software Design