Writing Comments – Beginner’s Guide to Writing Comments

One thing nobody's mentioned yet, so I'll mention it: The desire to nest comments often indicates that the programmer is Doing It Wrong.

First, let's agree that the only time "nesting" or "not nesting" is visible to the programmer is when the programmer writes something structurally like this:

do_something();
/* comment /* nested comment */ more comment */
do_something_else();

Now, when does such a thing come up in practice? Certainly the programmer isn't going to be writing nested comments that literally look like the above snippet! No, in practice when we nest comments (or wish we could nest them), it's because we want to write something like this:

do_something();  /* do a thing */
/* [ajo] 2017-12-03 this turned out to be unnecessary
do_something_else(); /* do another thing */
*/

And this is BAD. This is not a pattern we (as language designers) want to encourage! The correct way to write the above snippet is:

do_something();  /* do a thing */

That "wrong" code, that false start or whatever it was, doesn't belong in the codebase. It belongs, at best, in the source-control history. Ideally, you'd never even write the wrong code to begin with, right? And if the wrong code was serving a purpose there, by warning maintainers not to reinstate it for some reason, well, that's probably a job for a well-written and intentional code comment. Trying to express "don't do X" by just leaving in some old code that does X, but commented out, is not the most readable or effective way to keep people from doing X.

This all boils down to a simple rule of thumb that you may have heard before: Don't comment out code. (Searching for this phrase will turn up a lot of opinions in agreement.)

Before you ask: yes, languages such as C, C#, and C++ already give the programmer another tool to "comment out" large blocks of code: #if 0. But this is just a particular application of the C preprocessor, which is a large and useful tool in its own right. It would actually be extremely difficult and special-casey for a language to support conditional compilation with #if and yet not support #if 0.

So, we've established that nested comments are relevant only when the programmer is commenting out code; and we've established (via consensus of a lot of experienced programmers) that commenting out code is a Bad Thing.

To complete the syllogism, we must accept that language designers have an interest in promoting Good Things and discouraging Bad Things (assuming that all else is equal).

In the case of nested comments, all else is equal — you can safely ignore the low-voted answers that claim that parsing nested /* would somehow be "difficult" for the parser. (Nested /* are no harder than nested (, which just about every parser in the world already needs to handle.)

So, all else being equal, should a language designer make it easy to nest comments (i.e., to comment out code), or difficult? Recall that commenting out code is a Bad Thing.

Q.E.D.

Footnote. Notice that if you don't allow nested comments, then

hello /* foo*/bar.txt */ world

is a misleading "comment" — it's equivalent to

hello bar.txt */ world

(which is likely a syntax error). But if you do allow nested comments, then

hello /* foo/*.txt */ world

is a misleading "comment" — it's equivalent to

hello

but leaves the comment open all the way to the end of the file (which again is almost certainly a syntax error). So neither way is particularly less prone to unintentional syntax errors. The only difference is in how they handle the intentional antipattern of commented-out code.

Your question implies a dichotomy that doesn't exist.

Should you write cleaner code, if doing so will make it clear enough where you don't have to document it? Absolutely.

Should you write comments and otherwise provide documentation, when it will improve the clarity and understanding of the code? Of course.

Why are these two things not mutually exclusive?

1. Some of the code that you write will favor better performance over high readability.
2. Architecture is not self-documenting. While code in isolation is generally fairly easy to understand if it's written cleanly, the architecture surrounding it is not always.
3. Design decisions are not always self-evident.
4. What business process or problem the code solves is not always self-evident.

In short, you can't write non-trivial code in such a way that it is always completely self-describing. Part of your job is to insure that the fellow coming after you doesn't require a year to figure out your code, and for that, good documentation is a necessity.