[COFF] Code/comment Ratios Style

[Chet Ramey via COFF]

On 7/21/25 6:26 PM, josh wrote:
> On Monday, July 21, 2025, Chet Ramey via COFF <coff at tuhs.org 
> <mailto:coff at tuhs.org>> wrote:
> 
>     On 7/21/25 11:27 AM, Paul Winalski wrote:
> 
>         When writing all but the most trivial bug fixes I always put in a
>         comment referring to the bug report number.  This helps with what
>         can otherwise be a perplexing problem:  "why is this bit of code
>         there?"
> 
> 
>     I put those in the change log entries.
> 
> 
> Does anyone else feel like this is still an unsolved problem?
> 
> It seems git blame continues to be the state of the art for connecting a 
> section of code to the “commit” (or analogous concept) in which it was 
> added, which is where one would include context about why the change was 
> made and connect it to the wider world (bug tracker, etc).

I don't like commit messages that are paragraph length. That seems more
appropriate for a separate change log.


> Maybe this is a fundamental trade-off of code being plain text rather than 
> being stored as some rich/structured representation.

This sounds like some of the `literate programming' strategies, which
interleave the code and its documentation.


-- 
``The lyf so short, the craft so long to lerne.'' - Chaucer
		 ``Ars longa, vita brevis'' - Hippocrates
Chet Ramey, UTech, CWRU    chet at case.edu    http://tiswww.cwru.edu/~chet/