Mythryl >

---

Block comments ∞

/*
If you want to add a lot of comments, you can use this other style.
Just remember to put the asterisks on the inside.
Some people indent their comments or show a column of asterisks.
Do what you prefer.
*/

/*
Nested comments are ok.
/*
This is valid
# So is this
*/
# No problem
*/

Effective comments ∞

Writing good comments is not just about adding a lot of text. Comments which are formatted effectively will make future reading easy.

If you indent your comments a little bit, they will stand out from regular code.

If all of your comments are indented by that same amount, skimming through your code becomes easier. The reader can choose to read either comments or code without needing to "find" one or the other.

Also, use paragraphs or bullet points. Let's rewrite the above example. I'll "reveal" the spaces using red middots ( · ) and the extra paragraphs using cyan pillcrows ( ¶ ).

/*
··If you want to add a lot of comments, use this other style.
¶
··Just remember to put the asterisks on the inside.
¶
··Some people indent their comments or show a column of asterisks.
··Do what you prefer.
*/

Perhaps two spaces is enough of an indent for you. Maybe three is more pleasant. Whichever you choose, generally stick with it but it is perfectly fine for you to decide on more or less spaces, in order to make any specific case more readable.

Do not sacrifice readability to convention. Not ever.

Do not fret over:

• The extra spaces "making your program bigger".

  • Disk space is cheap compared to wasted time with awkward comments.

• The extra time it takes to "make everything pretty".

  • The time you take to write your comments well and format them clearly is time you and everyone else reading your code in the future won't have to spend again and again.

For me, I'm (hopefully) "in the zone" when programming, and I worry that the change in mindset from programming to formatting may disrupt my flow. In practice this doesn't seem to really matter, and I even benefit from these small breaks.

Line versus block comments ∞

Cynbe reported on the mailing list [edited]:

Even when doing a block of comments, I prefer the hashmark style because:

They are more uniform and maintainable:

You can re-order the lines arbitrarily in

# This
# that
# 'tother.

but not in

/*  This
 *  that
 */ 'tother.

No risk of runaway comments:

You don't have to worry about a # appearing somewhere inside a # ... comment, but you do need to worry about a /* or */ appearing accidentally somewhere inside a /*...*/ comment. This is easier than it looks, for example you might mention a Perl fragment like $string =~ /[a-z]*/ in a comment and -- BANG! -- you've got an unexpected */ in your comment. With just a little bit more bad luck, you've got a silent compile error that may have to be tracked down via debugging at runtime -- very good to avoid! And habitually always using hashmark comments is a sure-fire way to completely eliminate all such problems from your life.

I find that nearly the only time I wind up wanting a /*...*/ comment these days is when I have some call like

foo( 1, 13, 12, 96 );

where I want to document the arguments inline:

foo( /*count:*/ 1, /*age:*/ 13, /*parts:*/ 12, /*warranty days:*/ 96 );

.. and in those cases it is usually best anyhow to switch from a tuple to a record:

foo { count => 1, age => 13, parts => 12, warranty_days => 96 );

If that doesn't make sense, I'll probably just go for

foo
  ( 1,       # Count.
    13,      # Age.
    12,      # Parts.
    96       # Warranty days.
  );

which is really more readable -- you can skim down just the left side if you know what is going on, skipping the comments, and you can have longer, clearer comments on the right side to remind you when you've forgotten what is going on.

So it has to be a pretty unusual situation for a /* ... */ comment to look like the best solution, to my eyes at least. If we didn't already have them, I don't think I'd bother implementing them. But since we do have them, and just occasionally they do come in handy, I think they are worth keeping.