Add a comment policy to CONTRIBUTING.md #40

Merged

mysticalsoap merged 2 commits from docs/comment-policy into trunk

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

mysticalsoap commented

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

Owner

Problem

The codebase is over-commented and trimming has been case-by-case with no stated standard. Closes #27.

Fix

Adds a Comments section to CONTRIBUTING.md, placed right after Commits as the flip side of its principle: the commit body is the record of why, so a comment earns its place only by carrying what the code plus git blame cannot — a non-obvious external constraint, a warning that the obvious simplification is wrong, or a deliberate deviation from the surrounding pattern.

The issue proposed an explicitly AI-binding clause; deliberately dropped — the policy is tool-agnostic and covers generated code by construction, matching the rest of the file (which names no authoring tools anywhere).

Second commit applies the policy across the codebase, starting from the issue's model case (restore_default_dns): deletes comments restating the code, structure labels, and commented-out code; rewords the few restaters that hid a real constraint; keeps everything naming a non-obvious constraint or warning off a wrong simplification. Comment-only diff, verified by filtering changed lines.

Verification

python -m py_compile aqomui/aqomui_service.py passes; the code change is comment-only, no behavior change.

## Problem The codebase is over-commented and trimming has been case-by-case with no stated standard. Closes #27. ## Fix Adds a Comments section to CONTRIBUTING.md, placed right after Commits as the flip side of its principle: the commit body is the record of why, so a comment earns its place only by carrying what the code plus `git blame` cannot — a non-obvious external constraint, a warning that the obvious simplification is wrong, or a deliberate deviation from the surrounding pattern. The issue proposed an explicitly AI-binding clause; deliberately dropped — the policy is tool-agnostic and covers generated code by construction, matching the rest of the file (which names no authoring tools anywhere). Second commit applies the policy across the codebase, starting from the issue's model case (`restore_default_dns`): deletes comments restating the code, structure labels, and commented-out code; rewords the few restaters that hid a real constraint; keeps everything naming a non-obvious constraint or warning off a wrong simplification. Comment-only diff, verified by filtering changed lines. ## Verification `python -m py_compile aqomui/aqomui_service.py` passes; the code change is comment-only, no behavior change.

mysticalsoap added 2 commits

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

add: a comment policy to CONTRIBUTING.md 52fdbdf7fb

The codebase has drifted over-commented, and trimming has been happening
case-by-case with no stated standard to point at. Encode the distinction
the Commits section already implies: the durable record of why lives in
commit messages, so a comment earns its place only by carrying what the
code plus git blame cannot.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

change: trim the restore_default_dns comment to the live constraint f73131f37c

First application of the new CONTRIBUTING.md comment policy: the
paragraph narrating what the previous implementation did wrong is
commit-message content, already recorded in the commit that made the
change.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

mysticalsoap added 1 commit

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

change: apply the comment policy across the codebase 2c9530c975

Sweep every module against the new CONTRIBUTING.md standard. Deleted:
comments restating the code beneath them, structure labels (#Server tab),
commented-out code, and narration too cryptic to carry anything (#we
can't be sure of that). Reworded the few that held a real constraint
under a restating surface -- the wg conf umask, OpenVPN's cwd-relative
cert paths, the double-hop iptables retry -- and dropped a history clause
from bypass.py. Comments naming non-obvious constraints, external
behavior, or warnings against wrong simplifications all stay.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

mysticalsoap force-pushed docs/comment-policy from 2c9530c975 to 449aa79ded

2026-08-18 17:41:51 -04:00

Compare

mysticalsoap merged commit 44b8b8ab1d into trunk

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

mysticalsoap deleted branch docs/comment-policy

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