documentation-guidelines

Provides guidelines for writing code comments, JSDoc, and interface documentation.

1|Updated Dec 1, 2025

Search Tags:#code quality #documentation #coding standards #maintainability #comments #jsdoc

Ready to run

npx skills add https://github.com/hypeJunction/ai-assistant-starter --skill documentation-guidelines-hypejunction

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: documentation-guidelines
Source: https://github.com/hypeJunction/ai-assistant-starter/tree/main/skills/documentation-guidelines
Command: npx skills add https://github.com/hypeJunction/ai-assistant-starter --skill documentation-guidelines-hypejunction

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill provides clear guidelines on how to write effective code documentation, ensuring consistency and maintainability across projects. It helps developers understand when and how to add comments, JSDoc, and other forms of documentation.

Core Features & Use Cases

Best Practices: Learn when to comment and when not to, focusing on explaining the "why" not the "what."
TODO/FIXME Format: Standardizes how to mark deferred work or known bugs.
JSDoc and Interface Documentation: Provides examples for documenting functions and interfaces clearly.
Anti-Patterns: Highlights common mistakes to avoid in documentation.

Quick Start

Follow the documentation guidelines to improve the clarity of your code comments and JSDoc.

Frequently Asked Questions about documentation-guidelines

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

When should I add code comments and when should I avoid them?▼

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.

What is the best way to format TODO and FIXME entries in code documentation?▼

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.

How do I write effective JSDoc for functions and interfaces?▼

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.

What are common code documentation anti-patterns I should avoid?▼

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.

How does self-documenting code reduce the need for inline comments?▼

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.

Can I use these documentation guidelines for non-JSDoc projects?▼

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.