[COFF] Re: Code/comment Ratios Style

I just posted the most heavily commented code I have ever written. It's a radical (mis?)application of m4, which is about as inscrutable as any language short of APL. The ratio of comments to code is more than 3:1. It's at www.cs.dartmouth.edu/~doug/barem4.m4. 3:1 may be overkill, but I think 2:1 would not be unreasonable. Doug On Sun, Jul 20, 2025 at 5:26 PM Warren Toomey via COFF <coff(a)tuhs.org> wrote: > > I've written my fair share of code and also taught several languages. I'd > estimate my comment to total LOC ratio as about 1/4 to 1/3. But I keep > coming across code bases where the ratio is closer to 1/100 and it really > bugs me! I just can't read the codebase and work out the nuances of what > it is doing. > > 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.? > > 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. > > Thanks! > Warren