Inline Docs

Inline Documentation

Purpose

Provide concise, high-value inline documentation practices (comments and short docblocks) that improve safety, maintainability, and traceability without cluttering code.

When to Apply

• Safety-relevant code paths, interfaces, state machines, and algorithms.
• Boundary validations, error handling, and concurrency/interrupt sections.
• Any location requiring traceability to requirements/risks/tests.

Requirements (testable)

1. Comment Value: Inline docs must add intent, rationale, constraints, or traceability—not restate code. Rationale: clarity without noise.
2. Traceability Tags: Use stable IDs (REQ-###, RISK-CTRL-###, TEST-###) adjacent to safety/requirement code. Rationale: audit and impact analysis.
3. Boundary Notes: Document assumptions (units, ranges, timing, concurrency/ISR safety) at boundaries. Rationale: correct usage and safety.
4. API Docblocks: Public APIs include purpose, params, ranges, return codes, side effects; keep brief and consistent. Rationale: safe integration.
5. Staleness Control: Remove/update comments when behavior changes; no inline history logs. Rationale: avoid misinformation.

Recommended Practices

• Prefer short comments over long narratives; move detailed rationale to design docs, link by ID.
• Note non-obvious tradeoffs (performance vs safety) and mitigations.
• For concurrency/ISR-sensitive sections, document which locks/ordering guarantees apply.
• Keep language precise and ASCII; avoid ambiguous abbreviations.

Patterns

Traceability + constraint:

// REQ-PWR-BATT-01: shutdown  risk: misleads reviewers.
- Missing range/unit notes on APIs -> risk: misuse and safety defects.
- No traceability tags on safety logic -> risk: audit gaps.
- Inline change logs -> risk: divergence from VCS truth.

## Verification Checklist
- [ ] Comments add intent/constraints/traceability, not restate code.
- [ ] Traceability tags present on safety/requirement code.
- [ ] API docblocks include ranges, errors, side effects.
- [ ] Boundary assumptions (units/timing/concurrency) documented.
- [ ] Stale or inline history comments removed/updated.

## Traceability
- Use IDs from requirements/hazards/tests in inline comments; ensure they match external artifacts. Link to design docs by ID when more detail is needed.

## References
- IEC 62304 traceability expectations.
- ISO 14971 for risk-control linkage.
- DOC-CODE-COMMENTS and DOC-TRACEABILITY skills for complementary guidance.

## Changelog
- 1.0.0 (2026-01-04): Initial inline documentation skill with traceability, API docblocks, and boundary note guidance.

## Audit History
- **2026-01-04**: Audit performed. Verified:
  - IEC 62304 traceability expectations correctly referenced
  - ISO 14971 risk-control linkage accurate

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [AminAlam](https://github.com/AminAlam)
- **Source:** [AminAlam/meddev-agent-skills](https://github.com/AminAlam/meddev-agent-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.