documenting-code-comments

Comments explaining WHY focus on the reasoning behind decisions rather than restating code logic. Use comments to document intent, trade-offs, and non-obvious constraints; let self-documenting code and type systems convey WHAT the code does. This reduces comment drift and keeps documentation aligned with actual implementation.

Add comments for non-obvious decisions, business logic rationale, and complex algorithms. Avoid comments restating readable code or obvious operations. Use self-documenting practices—clear naming, type annotations, and JSDoc/TSDoc for public APIs—to minimize the need for inline comments and keep documentation maintainable.

Use consistent TODO formats with context and ownership, and apply JSDoc or TSDoc conventions for public APIs to document parameters, return types, and exceptions. Standardized formatting ensures comments remain searchable, maintainable, and consistent across projects during code reviews and audits.

Audit code systematically by checking that comments explain WHY decisions were made, not what the code does; verify type annotations and self-documenting names reduce redundant comments; and enforce TODO and JSDoc standards. Regular audits prevent comment drift and keep documentation accurate as code evolves.

Yes. JSDoc applies to JavaScript; TSDoc extends JSDoc for TypeScript with type-specific annotations. Both follow similar formatting conventions and serve the same purpose: documenting public APIs and reducing inline comment burden. Apply the appropriate standard for your language to maintain consistency.

Self-documenting code uses clear naming, type systems, and logical structure to make intent explicit without explanation. When variable names, function signatures, and types convey purpose and constraints, comments can focus solely on WHY decisions exist rather than restating obvious logic, making documentation leaner and more maintainable.