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".