code-commenting-ai-kit

To write self-documenting code, prefer clearer variable names and refactoring over explanatory commentary. This approach reduces clutter by ensuring the code explains itself, reserving comments only for non-obvious logic and business rules.

You should add comments for complex algorithms or regexes to explain their intent and constraints. Focus on documenting the WHY rather than the WHAT, ensuring maintainability when the logic is non-obvious or involves API gotchas.

The best way to format TODO and FIXME tags is to make them actionable and time-proof. Convert low-value notes into high-value annotations like FIXME, SECURITY, or HACK only when they add durable context and clear intent.

To remove outdated comments during refactoring, review the snippet to eliminate redundant or stale notes that repeat the code. Rewrite them only if they provide necessary WHY-focused context or actionable TODO-style annotations.

Yes, this commenting approach works for JavaScript-style annotations and docstrings. It provides appropriate annotation guidance across general programming, satisfying requirements to avoid redundant comments while explaining complex logic.

Comments should explain business logic because the code itself already shows what it does. Explaining the WHY adds durable context for maintainability, preventing confusion from comments that merely repeat the code or go stale.