Multi-line comments considered harmful
Recently on the ruby-core mailing list, someone asked why Ruby doesn’t have multi-line comments. I did a few searches, and didn’t find much discussion of the evils of multi-line comments. I thought it was common knowledge that they were a bad thing and a historical mistake made by Kernighan and Ritchie, but apparently not. So, here’s my opinion on the matter.
Superficially, multi-line comments seem like a handy thing to have, especially if you often comment out blocks of code temporarily during development. However, as soon as you allow multi-line comments, you need to decide what to do about nested multi-line comments–that is, what should happen when the ‘start comment’ sequence occurs inside a comment.
Option 1 is to allow it and make it not special. This is bad because it makes it very easy to end up with a run-away comment:
/* set variables
param = 0
/* set maximum size */
maxs = 100
Here ‘param’ ends up unset. This kind of bug can be really hard to locate.
Option 2 is to allow the start-comment sequence within a comment, and make comment pairs stack, so you need as many end-comment sequences as start-comment sequences. This at least makes errors like the above cause a compile-time failure, but it still makes them a pain to locate; you end up having to use something like vim’s ‘%’ command to play match-the-comment-delimiters until you spot which pair is mismatched. That’s no fun, especially once your comments contain pages of documentation. Ask a Java programmer…
Option 3 is to disallow nested comments, in which case multi-line comments can’t be used to comment out blocks of code which contain multi-line comments. That makes them pretty useless for temporary disabling of code; it would also cripple their use in rdoc.
Single-line comments have none of the above problems. You always know the comment will end when the next line starts. You can always comment out a block of code, no matter how many comments or comments-within-comments it contains. You never get runaway comments, and you never have to match up comment delimiters. The only downside to single-line comments is that it’s harder to comment out and un-comment-out multiple lines. That’s easily solved by using any good text editor.
All of which is why C++ introduced single-line comments, and C99 added them to regular C.
So in short, multi-line comments have no significant advantages, make parsing harder, and make errors more likely. I think Matz was entirely right not to put them in Ruby. As a rule, the only place I use multi-line comments is for JavaDoc, and that’s only because I have to.