Re: Block Comments Or Rest-Of-Line Comments?

Lawrence D'Oliveiro <ldo@nz.invalid> wrote:

Since then, I’ve seen newer programmers gravitate towards the rest-of-line
form in preference to the block form, and I’m not sure why. I’m fond of
writing things like
 
/*
    A very simple HTML/XML entity-escape function--why isn’t this
    part of the standard Java API?
*/
 
which involve less typing than
 
//
//  A very simple HTML/XML entity-escape function--why isn’t this
//  part of the standard Java API?
//

For me, it's block form for larger blocks of comment (descriptive stuff,
really, where a lot of info is needed).

Shorter comments use the rest-of-line form.

Since most of the comments I put in code are short (usually just to
describe what the next section does, if necessary, and typically are a
single line) they end up being mostly rest-of-line.

At work, with the autodoc system we use in Visual Studio, it requires
comment blocks which have 3 slashes ( /// ). Not a fan, but no choice
there either.

Also, the “block” form allows “interspersed” comments, where a short
comment can be put in the middle of a line and followed by more program
text in the rest of the line. For example, as a way of keeping long
argument lists straight:
 
    gdImageCopyResampled
      (
        /*dst =*/ ResizedFrame,
        /*src =*/ Context.StillFrame,
        /*dstX =*/ 0,
        /*dstY =*/ 0,
        /*srcX =*/ 0,
        /*srcY =*/ 0,
        /*dstW =*/ ResizedFrame->sx,
        /*dstH =*/ ResizedFrame->sy,
        /*srcW =*/ Context.StillFrame->sx,
        /*srcH =*/ Context.StillFrame->sy
      );

Ewww, no. That's a perfect case for end-of-line rest-of-line comments
after each line. Or refactoring the function signature somehow if
possible because that's a lot of parameters. Interspersed is just
messy-looking IMO. :)

One use for this though: if I'm making temporary changes to test
something out, I'll often comment out a bit of a line using /* .. */ but it's
solely for test purposes, and never ends up being committed.

Also some of this becomes moot anyway if a project has style guidelines,
not to mention automation in some editors (it's only more typing if the
editor doesn't autocomplete it for you).

--
Paul.