[COFF] Code/comment Ratios Style
Larry McVoy
lm at mcvoy.com
Mon Jul 21 12:01:18 AEST 2025
Take the "." off the end of Dougs url.
On Sun, Jul 20, 2025 at 08:30:45PM -0400, 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
--
---
Larry McVoy Retired to fishing http://www.mcvoy.com/lm/boat
More information about the COFF
mailing list