[COFF] Code/comment Ratios Style

[John P. Linderman]

Norm Schryer used to say "If the code and comments disagree, both are
probably wrong."

On Sun, Jul 20, 2025 at 7:42 PM Larry McVoy <lm at mcvoy.com> wrote:

> On Mon, Jul 21, 2025 at 07:26:07AM +1000, Warren Toomey via COFF wrote:
> > So this isn't a rant so much as a request for alternate perspectives. If
> > you have a spartan commenting style, why? Can you read your code and see
> > all the implications, or do you dislike lots of comments, or do you write
> > more external documentation etc.?
>
> Well, in a long lived code base, comments can rot.  I'd much rather have
> to read the code and figure it out than have a comment that is no longer
> true send me down a wild goose chase (it's happened more than I care to
> think about).
>
> I tend to comment structures quite a bit, globals and locals,
> have a block comment above the function saying what it is and it
> gets sparse from there.  There may be inline comments but they need
> to do something a lot more useful than
>
>         i++;    // increment i <-- this sort of comment is worse than
> useless
>
> I also have a style that is
>
>         int     *p = 0;
>         char    *foo = 0;
>         int     ret = 0;
>
>         // lots of code
> err:    ret = -1;
> out:    if (p) free(p);
>         if (foo) free(foo);
>         return (ret);
> }
>
> Most of the BitKeeper code follows that style, no unitialized pointers,
> we did use a lot of
>
>         unless (p = malloc(whatever)) goto err;
>
> style of programming.  Memory management in C is primitive so you have to
> adopt some consistent style to avoid errors just because someone did
> something different.
>
> > When I taught, I had two mantras about comments:
> >
> >  Code explains how, comments explain why.
> >
> >  Code as if the person who takes over your codebase
> >  is a crazed psychopath who knows where you live.
>
> I always said "optimize for reading, not writing".  I've also said
> "anything
> that you wrote 6 months ago, you will approach it as if it is someone
> else's
> code".
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.tuhs.org/pipermail/coff/attachments/20250720/28eef431/attachment.htm>