Add a rainix-static check that caps the ratio of comment lines to source lines, the way agent-context-cap caps agent context.
Rationale is the same as that cap's: a comment is an unverified claim that rots. It is not compiled, not tested, and nothing fails when it stops being true. rainlang#563's review found natspec asserting that the expression deployer "reaches the parser, store and interpreter" — false, and it survived authoring and review because prose is not checked by anything. Volume is the mechanism: the more comments there are, the less any individual one is read, and the more surface there is to go stale.
Shape, following agent-context-cap:
- Floor-only ratchet. The cap may be lowered as repos get leaner, never raised to fit new prose. Enforce it the way
agent_context_cap.rs does — a const _: () = assert!(RATIO <= <current>) so raising it is a compile error, not a test edit.
- Ratio, not absolute count, so a large repo is not penalised for existing and a small one cannot hide.
- Per-repo starting value set from the current measurement, so adopting the check is not a mass rewrite; each repo ratchets down from where it is.
Details worth deciding before implementing:
- What counts as a comment line:
//, /* */ and natspec /// alike. Natspec is where the volume actually is in the solidity repos, so exempting it would defeat the check.
- What counts as source: non-blank, non-comment lines. Generated files under
src/generated/ should be excluded from both numerator and denominator — their headers are machine-written and their bodies are hex blobs, so they would distort the ratio in both directions.
- Whether SPDX headers are exempt. Every
.sol file carries two, reuse lint requires them, and a small file is then mostly header. Probably exempt.
- Scope: whether it applies to
test/ at the same ratio as src/.
The measurement is what should drive the initial values — run it across the org before picking numbers, and expect the deploy repos to be the worst offenders, since the migrations landed with heavy explanatory natspec.
Add a
rainix-staticcheck that caps the ratio of comment lines to source lines, the wayagent-context-capcaps agent context.Rationale is the same as that cap's: a comment is an unverified claim that rots. It is not compiled, not tested, and nothing fails when it stops being true. rainlang#563's review found natspec asserting that the expression deployer "reaches the parser, store and interpreter" — false, and it survived authoring and review because prose is not checked by anything. Volume is the mechanism: the more comments there are, the less any individual one is read, and the more surface there is to go stale.
Shape, following
agent-context-cap:agent_context_cap.rsdoes — aconst _: () = assert!(RATIO <= <current>)so raising it is a compile error, not a test edit.Details worth deciding before implementing:
//,/* */and natspec///alike. Natspec is where the volume actually is in the solidity repos, so exempting it would defeat the check.src/generated/should be excluded from both numerator and denominator — their headers are machine-written and their bodies are hex blobs, so they would distort the ratio in both directions..solfile carries two,reuse lintrequires them, and a small file is then mostly header. Probably exempt.test/at the same ratio assrc/.The measurement is what should drive the initial values — run it across the org before picking numbers, and expect the deploy repos to be the worst offenders, since the migrations landed with heavy explanatory natspec.