Chatty agents

[egpbos]

Our inline code comments, and to a lesser extent PR descriptions, have drifted from short notes to multi-paragraph essays over the last few months. The cost is readability: the "why" gets buried in narrative. This makes code reviews hard (for me).

Code comments (src/proteus, 2024-08 to now):

• Raw density barely changed (full-line comments ~12% to ~15%). Quantity is not the problem.
• Block structure changed sharply: comment lines in blocks of 5+ lines went from under 3% to ~35%; the longest single block grew from ~8 to 38 lines.
• A current example: Stop re-downloading cached FWL_DATA and AGNI data on every CI run #794 adds a 10-line comment for a one-line cache-key change, and an 8-line comment for a 4-line guard, in .github/actions/setup-proteus/action.yml.

PR descriptions (past year): median prose length has more than doubled, from tens of words to several hundred.

Proposal(s):

• Code comments: state the load-bearing "why" in 1-2 lines. Keep derivations and step-by-step narrative out of the code. We can add this to both CONTRIBUTING.md, but more importantly to CLAUDE.md (the impact of when we started using Claude is clearly measurable, I can show the graphs on request 😄 ).
• PR descriptions and commit messages are the right home for rationale and some provenance (i.e. alternatives tried, etc.), but keep them scannable: short summary first, detail below. For this, we could slightly alter the PR template, mainly: add a very short matter of fact changelog-for-this-PR summary at the top. We could add the strict separation of content also in the form of comments in the template, so agents will also be able to read that.
• Optional tools/ check flagging comment blocks longer than ~8 lines, warn-only.

One-line comments explaining a non-obvious decision are healthy. The target is the essays.

[nichollsh]

Agreed that this is becoming a problem. @stuitje suggested this, recently: https://github.com/DietrichGebert/ponytail

[egpbos]

https://github.com/DietrichGebert/ponytail

Lol, awesome.