Why do most programming languages not nest block comments?

Question

A few do, but not any of the popular ones as far as I know. Is there something bad about nesting comments?

I plan to have block comments nest in the (small) language I'm working on, but I would like to know if this is a bad idea.

Answer 1

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.

Answer 2

Because most of the implementations are using separate lexing and parsing stages, and for lexing they're using plain old regular expressions. Comments are treated as whitespaces - i.e., ignored tokens, and thus should be resolved entirely in a lexing pass. The only advantage of this approach is parsing speed. Numerous disadvantages include severe limitations on syntax (e.g., a need to maintain a fixed, context-independent set of keywords).

Answer 3

It's perfectly possible to make a lexer that can handle nested comments. When it's eating whitespace, when it sees /* it can increment a depth counter, and decrement it when it sees */, and stop when the depth is zero. That said, I've done many parsers, and never found a good reason for comments to nest.

If comments can nest, then a downside is it's easy to get their ends unbalanced, and unless you have a fancy editor, it can invisibly hide code you assume is there.

An upside of comments that don't nest is something like this:

/*
some code
more code
blah blah blah
/**/

where you can easily comment the code in or out by removing or adding the first line - a 1-line edit. Of course, if that code itself contains a comment, this would break, unless you also allow C++-style // comments in there. So that's what I tend to do.

Answer 4

Since nobody else mentioned it, I'll list a few languages that do support nested comments: Rexx, Modula-2, Modula-3, Oberon. Despite all the complaints here about difficulty and speed issues, none of those seem to have any huge problems.

Answer 5

A good point of nesting block comments is that you can comment out large portions of code easily (well, almost, unless you have the block comment end sequence in a string constant).

An alternative method is to prepend a bunch of line with the line comment start sequence if you have an editor that supports it.

Haskell has nested block comments, but most people dont seem to notice or to complain about it. I guess this is because people that do not expect nested comments tend to avoid them as this would be a lexical error in other languages.

Answer 6

Supporting nested block comments complicates the parser, which is both more work and it could increase the compile time. I guess it is not a very needed feature for a language, so it is better to use the time and effort on other improvements and optimizations.

In my opinion simplicity is always a good thing in designing anything. Keep in mind that it is easier to add a feature than to remove it. Once you allow nested comments and there are programs out there using it, you won't be able to take them out without breaking compatibility.

Answer 7

One probable reason is that nested comments must be handled by the parser, since the flavor of regular expressions commonly used in lexers don't support recursion. The simple ones can be eliminated as whitespace by the lexer, so they're simpler to implement in that way.

Answer 8

Who knows? I would guess because supporting nested comments is more work - you would have to maintain a stack of some sort, and because it complicates the language grammar.

Answer 9

Languages with nested comments: D, Haskell, Raku, Swift, Julia, Dart, Kotlin - to pick a few common ones. C has #if 0 ... #endif which works similar to nested comments, which means C++ also has it.

So it seems like the modern style is to include them as they're generally seen as a good idea. And comment syntax evolves, remember C didn't originally have // but rather that comes from C++.

There are some claims elsewhere that lexing would be harder with nested comments. Given that it's simple enough to do it manually AND it's straightforward to do in a tool like flex (for a solution, see this Stack Overflow question: https://stackoverflow.com/questions/34493467/how-to-handle-nested-comment-in-flex) it seems simple hard facts contradict that idea.

Not to mention that most popular languages use handwritten parsers and lexers: https://notes.eatonphil.com/parser-generators-vs-handwritten-parsers-survey-2021.html.

Answer 10

Once you define precisely what is and what isn’t a comment, it’s easy enough to implement. Nested comments would be slightly harder, but not so much that it would be a big deal.

So what’s the problem? Describing exactly what is and what isn’t a comment. And giving a description where you don’t have unexpected nested comments, when the user didn’t intend it.

Answer 11

Nested comments mean extra work for the parser. Usually when you see the start of a comment you ignore everything until the end comment marker. In order to support nested comments you have to parse the text in the comments as well. The biggest issue, though, is that a programmer has to be careful to close all nested comments correctly or it will lead to compilation errors. Correctly implementing a compiler is something that can be done but keeping track of nested comments as a programmer is quite error-prone and irritating.