code-documentation

Guide code comments and documentation to explain rationale and design decisions.

8|Updated Nov 4, 2025

Search Tags:#documentation #comments #code-quality #docstrings #JSDoc

Ready to run

npx skills add https://github.com/ilude/claude-code-config --skill code-documentation-ilude

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: code-documentation
Source: https://github.com/ilude/claude-code-config/tree/main/skills/code-documentation
Command: npx skills add https://github.com/ilude/claude-code-config --skill code-documentation-ilude

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill promotes self-documenting code and focuses comments on WHY rather than WHAT.

Core Features & Use Cases

Comment philosophy: when to add comments (explain rationale, complex logic, API contracts).
Anti-patterns: avoid obvious, redundant, or outdated comments.
Good examples: show how to write meaningful docstrings and inline comments.

Quick Start

Review a function's comments and add a docstring for non-obvious behavior where needed.

Frequently Asked Questions about code-documentation

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

FAQPage Schema

How do I write documentation that explains the WHY behind my code decisions?▼

Focus comments on rationale and design intent rather than restating what the code does. Document non-obvious behavior, complex logic, and API contracts to help maintainers understand your reasoning and the problems you solved.

What makes a good docstring in Python or JSDoc?▼

Good docstrings explain purpose, parameters, return values, and edge cases without restating obvious code. Include examples for non-trivial behavior and highlight design decisions that aren't apparent from the function signature.

When should I add comments to my code?▼

Add comments to explain why a design choice was made, clarify complex algorithms, document API contracts, and capture constraints or trade-offs. Avoid comments that merely repeat what the code obviously does or describe syntax.

How do I avoid writing redundant or outdated comments?▼

Write self-explanatory code with clear naming first, then add comments only where intent isn't obvious. Keep comments tied to immutable facts—rationale and constraints—rather than implementation details that change with refactoring.

What are anti-patterns in code documentation?▼

Anti-patterns include obvious comments restating syntax, outdated documentation that contradicts current code, vague explanations without context, and missing API documentation for public functions. These create noise instead of clarity.

How do I document public APIs effectively?▼

Document public APIs with clear contracts: purpose, parameters, return types, exceptions, and usage examples. Explain design decisions and constraints so consumers understand when and how to use each endpoint or function.