code-comment-improver

Focus on explaining why the code exists rather than what it does, since the code itself shows the what. Document edge cases, business logic context, and workarounds with links to tickets or specifications.

Include a brief description, detailed explanation if needed, and tags for parameters, return values, thrown errors, and a usage example. This gives readers the contract of the function without reading its implementation.

A TODO should name an owner, describe what needs to be done, and reference a ticket or issue. FIXME comments should state what is broken and why the fix is deferred, while HACK comments explain when the workaround can be removed.

Avoid comments that restate obvious code behavior, such as labeling an increment operation. Redundant comments drift out of sync with code and add noise; reserve comments for non-obvious logic and constraints.

The comment principles and templates are language-agnostic, covering inline, block, header, and function documentation styles. The provided examples use JavaScript, Python, and React JSX, but the same rules apply elsewhere.