# Doc Inline Clean

> Guidelines for writing self-documenting code and knowing when (and how) to use comments.

- Skill: `jcorpac/doc-inline-clean` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jcorpac/doc-inline-clean`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jcorpac/doc-inline-clean/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: jcorpac (https://skillmd.com/u/jcorpac)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jcorpac/doc-inline-clean

---


# Inline Documentation & Clean Code

Code should be written for human readers first and computers second.

## Self-Documenting Code
The best documentation is code that reveals its intent without comments:
- **Descriptive Names**: `calculate_interest_rate()` instead of `cir()`.
- **Small Functions**: Break complex logic into smaller, well-named pieces.
- **Explain with Code**: `is_valid_user = user.active and not user.banned` instead of a comment explaining the `if` condition.

## When to Comment
- **Explain WHY, not WHAT**: Don't comment what the code does; explain the non-obvious rationale behind it.
- **Legal/Attribution**: For licenses or inherited complex algorithms.
- **Warnings**: "Don't change this order, it will break [Service X]".
- **TODOs**: Tracking debt or future work (but keep these to a minimum).

## Bad Comments
- **Redundant**: `i = i + 1  # Increment i`.
- **Stale**: Comments that refer to old versions of code.
- **Zombie Code**: Commented-out blocks of code that "we might need later". (Use Git for that instead).

## Summary
If you feel the need to write a comment explaining *how* something works, consider refactoring the code to be clearer instead.