When is the best time to add a new comment? Answer: before writing the code!
You might think adding comments before code will be impossible, how can you know the details of the code before you have written it? Well, you can’t, and that is exactly why writing comments first will make your comments a lot better!
Let me elaborate. Comments in code should explain things that are not obvious from reading the code, the things that you had in mind when writing it that cannot be expressed clearly by the code itself. Comments also allows for a different level of abstraction than code.
So, when you realize that you want to add a new class, start with writing down what the class should be used for, what it represents. Don’t write any implementation details, they are better represented by the code that you add later. As an example, imagine that you want to add a class representing a blogpost, it can start out like this:
/**
* This class implements a blogpost.
* A blogpost consists of a number of elements, such as a
* reference to the author, a title, body text, etc.
* that together makes up it's contents.
*/
class blogpost {
};
The comment above is a high level description of the class. It gives anyone that opens up the file a quick overview of what it is without going into any technical details.
As you implement the class you may soon realize that there is a need for a way to embed different media elements, such a images, videos, and sound clips. You decide to add a method for this to the public interface of the class and start by writing a comment:
/* Insert a media element (image, video, or sound clip).
* By default the element will be inserted at the end of the
* current body, but an absolute position value can be
* provided, in which case the element will be inserted
* directly after that position.
* In case an invalid position value is provided (either
* negative or larger than the current body) the default
* position will be used.
*/
void insert_media(const MediaElement& elem, int pos = -1);
This comment also provides a high level description of what the method does. It tells the developer looking to use it where in the body the element will be placed and how to use the position argument to change that position if needed. What it doesn’t do is describe how the media element is inserted, and that is exactly how it should be. If a developer needs to know the technical details the implementation code is where that information can be found.
If you follow the advise to add comments first, your comments will be better and it will be more pleasant to add them. Waiting with adding comments to after all the code has been written will feel like a burden, requiring you to to go through all the code, trying to remember your thoughts at the time. It is a big risk you will skip adding comments, or just add comments that describe the same thing that the code does, which results in useless comments.