Comment Style
Comments should explain constraints, invariants, and non-obvious tradeoffs; delete comments that merely restate code. Source: Dedalus Style Guide; skills/engineering/lerp/SKILL.md
Kevin's comment style is sparse and operational. A good comment makes review cheaper by recording a constraint the code alone cannot show: why a value is chosen, what invariant must hold, which external API is strange, or what failure mode the next editor must not reintroduce.
Bad comments narrate syntax. They create drift, make files louder, and train agents to pad code with fake clarity. When code changes, update or delete nearby comments in the same patch.
Use Security and Review Skills when inline comments annotate a structured list of dataclass fields, enum variants, config flags, or similar records. Alignment is valuable only when it helps scanning; otherwise prefer normal prose comments.
Rules
| Situation | Rule |
|---|---|
| Non-obvious invariant | Comment the invariant |
| External API oddity | Comment the constraint |
| Repeated reviewer question | Comment the answer |
| Code says the same thing | Delete the comment |
| Generated docs drift | Run Writing and Content Skills or Google Workspace Skills |
Defaults And Exceptions
Default to no comment when names, types, and structure can carry the meaning. Add a comment when the code has hidden context: provider behavior, historical bug, ordering constraint, security reason, performance tradeoff, or invariant that a future edit might violate.
Exceptions can be longer than the normal sparse style when they cite an upstream bug, protocol requirement, migration hazard, or safety invariant. In those cases the comment should include the source or issue link. Otherwise, if the comment needs a paragraph, the code likely needs a better boundary.
Proof
During review, scan every changed comment and ask whether deleting it would lose operational knowledge. If not, delete it. If the same explanation appears in multiple places, move it to a style page, workflow, skill, or helper name.
Style Rule Contract
This page follows Style Rule Contract: name the default pattern, banned pattern, reason, exception, proof, and codification path clearly enough that the next agent can apply the rule without asking Kevin again. If a local repo has a stricter rule, follow the local rule and update the wiki when the decision becomes durable.
Timeline
- 2026-07-01 | Aligned this page with Style Rule Contract so style guidance names default behavior, banned patterns, exceptions, proof, and codification expectations. Source: User request, 2026-07-01
- 2026-07-01 | Added defaults, exceptions, and proof rules so comments preserve hidden operational knowledge instead of narrating syntax. Source: User request, 2026-07-01