[COFF] Re: Code/comment Ratios Style

On Monday, July 21, 2025, Chet Ramey via COFF <coff(a)tuhs.org> wrote: 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). There is a lot to say about a change which would be extraneous to include in the code as comments — real-world context (as mentioned), trade-offs considered / why specific implementation decisions were made, explanation and annotation, potential future steps, testing/validation, and even rich media demonstrating things that may be hard to express in text.[1] This all goes in the “pull request” UI on GitHub, or the email thread discussing a patch. Now why does all this only have a tenuous connection to the actual code once it’s merged? Any little nudge will override the git blame. Shouldn’t there be a more formal connection between the code and its history? (Not to mention one doesn’t always think to check the history when reading code, that only becomes necessary when something isn’t clear. Let’s be honest, how often do we go out of our way to do this?). Maybe this is a fundamental trade-off of code being plain text rather than being stored as some rich/structured representation. Now that I wrote this all out, I’m starting to feel like I’ve heard flame wars about git blame before, so I’m sorry if I ended up beating a dead horse on accident :-P. Josh [1] I can see how having an outlet for all these things can remove incentives to make the code itself understandable without external reference, which is pretty problematic...