Add a comment policy to CONTRIBUTING.md #27

New issue

Closed

opened 2026-08-17 16:57:01 -04:00 by mysticalsoap · 0 comments

mysticalsoap commented

2026-08-17 16:57:01 -04:00

Owner

The codebase is over-commented, including by AI assistance, and it needs
a stated standard rather than repeated case-by-case trimming.

The distinction to encode: the durable record of why belongs in commit
messages, which CONTRIBUTING.md already says well. So comments are rare and
reserved for what a reader cannot recover from the code plus git blame.

Proposed shape -- write a comment only when it names a non-obvious external
constraint, warns that an obvious simplification is wrong, or explains a
deliberate deviation from the surrounding pattern. Never to restate code,
narrate the change's history, or label structure. Prefer a clearer name or a
smaller function over a comment explaining a confusing one.

Include the clause making this explicitly binding on AI-generated commentary,
since that is the stated source of the drift.

restore_default_dns (aqomui_service.py:288-294) is the model case: a
commit-message paragraph living in the source, where the content is already in
the commit body.

The codebase is over-commented, including by AI assistance, and it needs a stated standard rather than repeated case-by-case trimming. The distinction to encode: the durable record of *why* belongs in commit messages, which CONTRIBUTING.md already says well. So comments are rare and reserved for what a reader cannot recover from the code plus `git blame`. Proposed shape -- write a comment only when it names a non-obvious external constraint, warns that an obvious simplification is wrong, or explains a deliberate deviation from the surrounding pattern. Never to restate code, narrate the change's history, or label structure. Prefer a clearer name or a smaller function over a comment explaining a confusing one. Include the clause making this explicitly binding on AI-generated commentary, since that is the stated source of the drift. `restore_default_dns` (`aqomui_service.py:288-294`) is the model case: a commit-message paragraph living in the source, where the content is already in the commit body.

mysticalsoap added the

docs

label

2026-08-17 16:57:01 -04:00

mysticalsoap referenced this issue from a pull request that will close it,

2026-08-18 17:08:23 -04:00

Add a comment policy to CONTRIBUTING.md #40

mysticalsoap closed this issue

2026-08-18 17:42:16 -04:00