in-code-comments

Write clean code comments by explaining the 'why' behind design decisions rather than summarizing the 'how' of the code logic. This enforces clarity, reduces redundancy, and improves overall maintainability without stating the obvious.

The best way to avoid redundant comments is to ensure they provide contextual information not evident from the code itself. Comments should explain rationale and intent, preventing clutter and reducing the maintenance overhead of restating code.

Yes, this approach to code documentation applies to all source code generation and modification tasks across various programming languages. It enforces timeless, present-tense comments that explain design decisions regardless of the language used.

You should use a-temporal writing for in-code comments whenever you generate or modify source code. It promotes timeless, present-tense statements to avoid outdated historical references, ensuring documentation remains accurate as the codebase evolves.

Code comments need to explain the 'why' to address the problem of poorly written documentation that hinders maintainability. Explaining the rationale behind optimizations or trade-offs provides context that the code logic itself cannot convey.