Clean Code: Use Comments Only When Necessary

A beautiful code should be concise and correct. Since one’s instant memory is limited, the more you write, the more you forget, and the more exhausted you would be. A qualified programmer should only use comments when necessary.

Principle 1: Use Informative Naming To Avoid Comments

As we have discussed in Meaningful Naming, a qualified programmer should always use a name reflecting the variable or function’s purpose. By following this rule, there would be no need to add comments anymore.

Consider the example in Meaningful Naming:

int d; // Elapsed Time In Days.
int elapsedTimeInDays;

Which one would you prefer? The first one using an ambiguous name with a comment following it, or the second one using an informative name? I believe the second one would be easier for readers because the will get rid of the annoying navigation back and forth between the usage and the variable’s declaration.

For historical reasons, many old codes use abbreviations like d because it saves them lots of memory space in the 64KB-CD age. Memory and storage are precious at that time for source codes. However, now they are much cheaper, and from the programmers’ perspective, they are infinite for source codes: even if a source code with 1GB size will require you years to code. Everyone has the freedom to write source codes now.

More importantly, compared to computers’ memory which you can easily purchase, you cannot easily enlarge your brain’s memory. Programmers’ time is expensive: an experienced programmer may create value of hundreds of dollars per hour. Therefore, stop saving memory by writing ambiguous short names and use meaningful words instead.

Principle 2: Comment For Special Logic

Particular logic or conditions are the critical places to write comments. A typical program consists of IF-ELSE branches and WHILE-loops. However, sometimes the intention of conditions is mysterious for new readers, which may require a further explanation of the algorithm or logic. In this case, comments are necessary.

The following is a common example if one wants to implement a vector-comparison by hand:

bool operator==(const vector<int> &vector1, const vector<int> &vector2) {
  // Different vector size implies different contents.
  // Avoid array index overflow error.
  if (vector1.size() != vector2.size()) {
    return false;

  for (int index=0; index<vector1.size(); index++) {
    if (vector1[index] != vector2[index]) {
      return false;
  return true;  // No unmatched item found => Identical vectors.

Moreover, there should not be giant and complex logic in a function by adopting the small function principle. Therefore, the whole logic is more manageable, and the comments would be much clear to read.

Principle 3: Comment For Warning and TODO

Adding comments for warning and TODO would be an excellent software development suggestion, especially for the agile method.

Typical cases for warnings would be the case that an error may throw. For example, if a function is not thread-safe, we should write a warning comment initially. Moreover, if an error is going to throw in a function, we should also indicate the possible error in its declaration.

TODO comments are also helpful in the agile process. Usually, we will first define functions and interfaces from a sketch for a software architect, and then different teammates may implement various components separately to enhance the coding efficiency. In this case, a qualified architect should write TODO comments indicating what remains to do for each function. After the implementation and testing, the TODO comments should be removed.

In summary, a qualified programmer should only write essential comments to enhance the understanding of codes. If you remove a comment without decreasing the comprehension of the code, remove it! If you remove it, but the logic is puzzling, keep it!

Read more about the Clean Code series:

To buy the book:

3 thoughts on “Clean Code: Use Comments Only When Necessary

Leave a Reply

Your email address will not be published.