code-comments
Code Comments
Write documentation that lives with the code it describes. Plain language. No jargon. Explain the why, not the what.
Core Philosophy
Co-location wins. Documentation in separate files drifts out of sync. Comments next to code stay accurate because they're updated together.
Write for three audiences:
- Future you, six months from now
- Teammates reading unfamiliar code
- AI assistants (Claude, Copilot) who see one file at a time
The "why" test: Before writing a comment, ask: "Does this explain why this code exists or why it works this way?" If it only restates what the code does, skip it.
Documentation Levels
File Headers
More from idotta/skills
dotnet-recommended
Use when building .NET 10 or C# 14 applications; when using minimal APIs, modular monolith patterns, or feature folders; when implementing HTTP resilience, Options pattern, Channels, or validation; when seeing outdated patterns like old extension method syntax
19code-reviewer
Use this skill to review code. It supports both local changes (staged or working tree) and remote Pull Requests (by ID or URL). It focuses on correctness, maintainability, and adherence to project standards.
7docs-writer
Always use this skill when the task involves writing, reviewing, or editing files in the `/docs` directory or any `.md` files in the repository.
6ai-guidelines
Behavioral guidelines to reduce common LLM coding mistakes. Use when writing, reviewing, or refactoring code to avoid overcomplication, make surgical changes, surface assumptions, and define verifiable success criteria.
6