Path: ...!news.mixmin.net!eternal-september.org!feeder3.eternal-september.org!news.eternal-september.org!.POSTED!not-for-mail
From: paul@paulglover.net.invalid
Newsgroups: comp.lang.c
Subject: Re: Block Comments Or Rest-Of-Line Comments?
Date: Fri, 26 Apr 2024 22:32:34 -0000 (UTC)
Organization: A noiseless patient Spider
Lines: 65
Sender: Paul Glover <paul@bsd.lan>
Message-ID: <v0ha21$3ujjm$1@dont-email.me>
References: <utgjh0$21nsq$2@dont-email.me>
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Injection-Date: Sat, 27 Apr 2024 00:32:34 +0200 (CEST)
Injection-Info: dont-email.me; posting-host="96479a0e6d4a6889390c4a7ab23bc8c8";
	logging-data="4148854"; mail-complaints-to="abuse@eternal-september.org";	posting-account="U2FsdGVkX1+2430bSyofAUf5PWl5gynkZVTSLFuBVvY="
User-Agent: tin/2.6.3-20231224 ("Banff") (FreeBSD/14.0-RELEASE (amd64))
Cancel-Lock: sha1:Sq+F8HJhJ0M647nw8qDvnWAXoxo=
Bytes: 3342

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.