[COFF] Code/comment Ratios Style

[Charles H Sauer (he/him)]

Thanks for doing this. I added
dnl https://www.cs.dartmouth.edu/~doug/barem4.m4
to the top of my copy...

On 7/20/2025 7:30 PM, Douglas McIlroy wrote:
> 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 at 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

-- 
voice: +1.512.784.7526       e-mail: sauer at technologists.com
fax: +1.512.346.5240         Web: https://technologists.com/sauer/
Facebook/Google/LinkedIn/mas.to: CharlesHSauer