Skillshub common-documentation

Essential rules for code comments, READMEs, and technical docs. Use when adding comments, writing docstrings, creating READMEs, or updating any documentation. (triggers: comment, docstring, readme, documentation)

install

source · Clone the upstream repo

git clone https://github.com/ComeOnOliver/skillshub

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/ComeOnOliver/skillshub "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/HoangNguyen0403/agent-skills-standard/common-documentation" ~/.claude/skills/comeonoliver-skillshub-common-documentation && rm -rf "$T"

manifest: skills/HoangNguyen0403/agent-skills-standard/common-documentation/SKILL.md

source content

Documentation Standards

Priority: P2 (MAINTENANCE)

📝 Code Comments (Inline Docs)

"Why" over "What": Comments should explain non-obvious intent. Code should describe the logic.
Docstrings: Use triple-slash (Dart/Swift) or standard JSDoc (TS/JS) for all public functions and classes.
Maintenance: Delete "commented-out" code immediately; use Git history for retrieval.
TODOs: Use
```
TODO(username): description
```
or
```
FIXME
```
to track technical debt with ownership.
Workarounds: Document hacks and removal conditions (e.g., backend bug, version target).
Performance Notes: Explain trade-offs only when performance-driven changes are made.

📖 README Essentials

Mission: Clear one-sentence summary of the project purpose.
Onboarding: Provide exact Prerequisites (runtimes), Installation steps, and Usage examples.
Maintainability: Document inputs/outputs, known quirks, and troubleshooting tips.
Up-to-Date: Documentation is part of the feature; keep it synchronized with code changes.

🏛 Architectural & API Docs

ADRs: Document significant architectural changes and the "Why" in
```
docs/adr/
```
.
Docstrings: Document Classes and Functions with clear descriptions of Args, Returns, and usage Examples (
```
>>>
```
).
Diagrams: Use Mermaid.js inside Markdown to provide high-level system overviews.

🚀 API Documentation

Self-Documenting: Use Swagger/OpenAPI for REST or specialized doc generators for your language.
Examples: Provide copy-pasteable examples for every major endpoint or utility.
Contract First: Define the interface before the implementation.

Anti-Patterns

No "what" comments: Explain intent, not mechanics. Refactor instead.
No orphan TODOs: Every TODO needs
```
(owner)
```
and a linked ticket.
No out-of-date docs: Documentation ships with the feature, not after.