with-doc-comments
A doc comment earns its place only if it says something the signature does not. The reflex to fill every slot produces the dominant failure: @param userId The user ID. — a line that costs a read, satisfies the linter, blocks the "undocumented" warning that would have flagged the gap, and tells the caller nothing. The signature already carries names, types, arity, and nullability. The comment's job is the contract around them.
This holds identically when writing new comments and when auditing existing ones. Auditing is the same rules applied to text already on the page.
Before writing, read neighbouring files in the same module and match their dialect — tag vocabulary, tag ordering, whether the codebase links members by reference or inherits docs from a base type. House convention outranks the wording and formatting rules below; it does not override the coverage rules, which decide what gets documented at all.
Coverage
Decide what gets a comment before deciding how to word one.
- Document the whole public surface — every exported or public type, method, property, constant, event, and enum member, along with its parameters, return value, and thrown errors. A public member is a promise to someone who cannot read the implementation.
- Leave internals alone. Private and internal members get no doc comment, and do not fall back to an ordinary implementation comment either. Code that needs prose to be understood should be renamed, split, or restructured until it does not, and an invariant worth stating is worth enforcing — in the type system, a guard clause, or a test.
- No comment beats a restated one. When you cannot say more than the member's name already says, the member is either self-evident — leave it bare — or badly named. Renaming is the better fix.
- Never bulk-generate doc comments to clear a linter. The result is uniform noise that hides the members which genuinely needed explaining.
The summary sentence
Documentation generators index the first sentence alone. It has to stand by itself.