22 Jul
2025
22 Jul
'25
1:33 p.m.
On 7/21/25 6:26 PM, josh wrote:
On Monday, July 21, 2025, Chet Ramey via COFF
<coff(a)tuhs.org
<mailto:coff@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(a)case.edu http://tiswww.cwru.edu/~chet/