AminAlam 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)
- Comment Value: Inline docs must add intent, rationale, constraints, or traceability—not restate code. Rationale: clarity without noise.
- Traceability Tags: Use stable IDs (REQ-###, RISK-CTRL-###, TEST-###) adjacent to safety/requirement code. Rationale: audit and impact analysis.
- Boundary Notes: Document assumptions (units, ranges, timing, concurrency/ISR safety) at boundaries. Rationale: correct usage and safety.
- API Docblocks: Public APIs include purpose, params, ranges, return codes, side effects; keep brief and consistent. Rationale: safe integration.
- 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 <VBAT_CRIT; RISK-CTRL-55; TEST-PWR-04
if (vbat < VBAT_CRIT) { enter_safe_shutdown(); }
API docblock:
/**
* @brief Encrypt payload with device key (Class C path).
* @param out must have room for len+TAG_LEN; len <= MAX_PAYLOAD.
* @return 0 on success, -EIO on crypto failure.
* REQ-ENC-AEAD-01, TEST-ENC-04
*/
int secure_encrypt(uint8_t *out, size_t len, const uint8_t *in);
Concurrency note:
// Holds tx_mutex <= 2 ms; ISR-safe: no lock taken in ISR
Anti-Patterns (risks)
- Comments that mirror code or go stale -> 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