ChapterÂ 6.Â Making Comments Precise and Compact
The previous chapter was about realizing what you should be commenting. This chapter is about how to write comments that are precise and compact.
If youâre going to write a comment at all, it might as well be preciseâas specific and detailed as possible. On the other hand, comments take up extra space on the screen, and take extra time to read. So comments should also be compact.
Comments should have a high information-to-space ratio.
The rest of the chapter shows examples of how to do this.
Keep Comments Compact
Hereâs an example of a comment for a C++ type definition:
// The int is the CategoryType. // The first float in the inner pair is the 'score', // the second is the 'weight'. typedef hash_map<int, pair<float, float> > ScoreMap;
But why use three lines to explain it, when you can illustrate it in just one line?
// CategoryType -> (score, weight) typedef hash_map<int, pair<float, float> > ScoreMap;
Some comments need three lines of space, but this is not one of them.
Avoid Ambiguous Pronouns
As the classic âWhoâs on First?â skit illustrated, pronouns can make things very confusing.
It takes extra work for the reader to âresolveâ a pronoun. And in some cases, itâs unclear what âitâ or âthisâ is referring to. Hereâs an example:
// Insert the data into the cache, but check if it's too big first.
In this comment, ...