<div dir="ltr"><div class="gmail_default" style="font-size:small">Norm Schryer used to say "If the code and comments disagree, both are probably wrong."</div></div><br><div class="gmail_quote gmail_quote_container"><div dir="ltr" class="gmail_attr">On Sun, Jul 20, 2025 at 7:42 PM Larry McVoy <<a href="mailto:lm@mcvoy.com">lm@mcvoy.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">On Mon, Jul 21, 2025 at 07:26:07AM +1000, Warren Toomey via COFF wrote:<br>
> So this isn't a rant so much as a request for alternate perspectives. If<br>
> you have a spartan commenting style, why? Can you read your code and see<br>
> all the implications, or do you dislike lots of comments, or do you write<br>
> more external documentation etc.?<br>
<br>
Well, in a long lived code base, comments can rot.  I'd much rather have<br>
to read the code and figure it out than have a comment that is no longer<br>
true send me down a wild goose chase (it's happened more than I care to<br>
think about).<br>
<br>
I tend to comment structures quite a bit, globals and locals,<br>
have a block comment above the function saying what it is and it<br>
gets sparse from there.  There may be inline comments but they need<br>
to do something a lot more useful than<br>
<br>
        i++;    // increment i <-- this sort of comment is worse than useless<br>
<br>
I also have a style that is<br>
<br>
        int     *p = 0;<br>
        char    *foo = 0;<br>
        int     ret = 0;<br>
<br>
        // lots of code<br>
err:    ret = -1;<br>
out:    if (p) free(p);<br>
        if (foo) free(foo);<br>
        return (ret);<br>
}<br>
<br>
Most of the BitKeeper code follows that style, no unitialized pointers,<br>
we did use a lot of<br>
<br>
        unless (p = malloc(whatever)) goto err;<br>
<br>
style of programming.  Memory management in C is primitive so you have to<br>
adopt some consistent style to avoid errors just because someone did <br>
something different.<br>
<br>
> When I taught, I had two mantras about comments:<br>
> <br>
>  Code explains how, comments explain why.<br>
> <br>
>  Code as if the person who takes over your codebase<br>
>  is a crazed psychopath who knows where you live.<br>
<br>
I always said "optimize for reading, not writing".  I've also said "anything<br>
that you wrote 6 months ago, you will approach it as if it is someone else's<br>
code".<br>
</blockquote></div>