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.

Kaz Kylheku <433-929-6894@kylheku.com> wrote:
> I have a simpler approach: commits which introduced commented-out
> code, whether with #if 0, or any other means, shall not be merged.
>
> I don't perpetrate that in my open source projects, and "-1" such
> submissions at work.
>
> When someone wants to remove code, I encourage them to actually
> delete it. The comment about why it was deleted goes into the
> commit log.

Yes!! Every time a dev checks in dead code, $DEITY kills a small furry
creature out of spite.

Maybe it was appropriate 40 years ago before we had version control
systems, but we do now, and code deleted that needed to stay can easily
be brought back from the void. (I just had to do that in my day job, an
"unused" line which the IDE flagged actually was important and removing
it caused a runtime error. It was a 5 second fix when I could just pull
up the change details and pull the line back in.)

--
Paul.