documentation-guidelines

Code comments should explain the intent and the "why" behind decisions, not the mechanics of what the code is doing. You should avoid commenting when the code is already self-documenting, focusing instead on clarity and maintainability.

The best way to format TODO and FIXME entries is by using standardized notation that clearly marks deferred work or known bugs. Consistent formatting ensures these items are easily searchable and trackable across the project's maintainability lifecycle.

Effective JSDoc for functions and interfaces requires documenting parameters, return types, and behavior clearly. Following established documentation guidelines ensures your interface documentation is consistent, concise, and improves overall code maintainability.

Common documentation anti-patterns include over-commenting mechanics that are already obvious from self-documenting code, using inconsistent TODO formats, and neglecting interface documentation. These mistakes reduce clarity and harm long-term maintainability.

Self-documenting code reduces the need for inline comments by using clear naming and structure to explain mechanics. This allows developers to focus comments on explaining higher-level intent and the reasoning behind specific coding standards.

Yes, you can apply these documentation guidelines to non-JSDoc projects. The core principles of writing concise comments, standardizing TODO formats, and explaining intent over mechanics apply universally across coding standards and languages.