Code Commenting

Governs comments and documentation only. Does not change how the code itself is written.

Documentation format

Use the language's native doc-comment convention. Examples:

• C# → XML doc (///)
• Java → Javadoc (/** */)
• Python → docstrings
• JavaScript / TypeScript → JSDoc / TSDoc
• Go → doc comments (// Name ...)
• Rust → ///

For any other language, follow that language's accepted documentation standard.

File header

Add a concise header at the top of every file stating what the file is in general, in one or two lines. No implementation detail; detail belongs to the functions.

Function comments

Document every function with a comment describing what it does, not how. Skip functions that are trivial, self-evident, or not conventionally documented (getters, setters, one-liners whose name already says everything).

Inline comments

Add inline comments only where logic is complex or a decision is non-obvious: anything a later reader needs to follow the code. Explain the reason or key point, not the mechanics.

Style

• Concise but meaningful. Write for a human reader in natural language.
• No filler, no line-by-line narration, no AI-tell phrasing.
• Never add a comment that only states the obvious or adds nothing.

Existing comments (protected)

• Do not modify, rewrite, or delete existing comments while coding.
• Adding new comments is allowed freely.
• To change or remove an existing comment, including obvious or no-value ones, ask permission first.