[COFF] Code/comment Ratios Style

[Larry McVoy]

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