跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
开发与测试

meddev-code-comments

Provide conventions for code comments that support traceability to requirements, risks, and tests, while maintaining clarity and brevity. Use when working on code comments in medical device software.

AminAlam · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add AminAlam/meddev-agent-skills --skill meddev-code-comments

技能说明


name: meddev-code-comments description: Provide conventions for code comments that support traceability to requirements, risks, and tests, while maintaining clarity and brevity. Use when working on code comments in medical device software. license: MIT metadata: skill_id: DOC-CODE-COMMENTS version: 1.0.0 last_updated: '2026-01-04' applies_to: Class A, Class B, Class C jurisdiction: Global prerequisites: REG-ISO14971, REG-IEC62304, DOC-INLINE category: documentation

Code Documentation for Traceability

Purpose

Provide conventions for code comments that support traceability to requirements, risks, and tests, while maintaining clarity and brevity.

When to Apply

  • Any safety-related code, interfaces, or tests.
  • When implementing or modifying requirements or risk controls.

Requirements (testable)

  1. Traceability Tags: Use stable IDs (e.g., REQ-###, RISK-CTRL-###, TEST-###) in comments near implementing code. Rationale: link code to artifacts.
  2. Minimal Necessary Comments: Explain intent, constraints, and safety context; avoid restating obvious code. Rationale: clarity without noise.
  3. API Documentation: Public interfaces documented with purpose, parameters, ranges, error codes, and side effects. Rationale: correct usage.
  4. Change History: Avoid inline history; rely on VCS; only note rationale when non-obvious decisions impact safety. Rationale: reduce clutter.
  5. Generated Docs: Use Doxygen/Javadoc-style only where toolchains consume it; keep tags consistent. Rationale: consistency.

Recommended Practices

  • Co-locate traceability tags with logic they cover.
  • Note assumptions and safety limits (ranges, timing).
  • Keep comments in ASCII; avoid ambiguous abbreviations.
  • Remove stale comments during refactors.

Patterns

Traceability on requirement and risk control:

// REQ-221: stop pump within 50 ms on door open; RISK-CTRL-19; TEST-410
bool pump_stop_on_door_open(void) {
    ...
}

API doc example:

/**
 * @brief Set infusion rate.
 * @param ml_per_hr range [0, MAX_FLOW]; clamps and alarms if exceeded.
 * @return 0 on success, -ERANGE if clamped.
 * REQ-300, RISK-CTRL-27
 */
int set_flow(float ml_per_hr);

Anti-Patterns (risks)

  • No traceability tags -> risk: lost linkage in audits/impact analysis.
  • Commenting the obvious or mismatched comments -> risk: clutter/confusion.
  • Inline change logs instead of VCS -> risk: divergence.
  • Missing parameter ranges -> risk: misuse of APIs.

Verification Checklist

  • Requirements/risk/test IDs present where applicable.
  • Comments capture intent/constraints, not restating code.
  • Public APIs documented with params, ranges, errors.
  • Stale/misleading comments removed.
  • Documentation style consistent (Doxygen/Javadoc if used).

Traceability

  • Tags REQ-###, RISK-CTRL-###, TEST-### aligned with external artifacts; code review enforces presence on safety-relevant sections.

References

  • IEC 62304 traceability expectations.
  • ISO 14971 linkage of controls to implementation.

Changelog

  • 1.0.0 (2026-01-04): Initial code comment/traceability guidance.

Audit History

  • 2026-01-04: Audit performed. Verified:
    • IEC 62304 traceability expectations correctly referenced
    • ISO 14971 linkage requirements accurate