# annotations

> Annotation and documentation protocol for rapid-iteration projects (“vibe coding”). Enforces Google Docstring Style plus comment-as-contract: consistency with signatures/types, explicit pre/post-conditions, units/frames/conventions, and rich implementation comments. Use Notes with ASCII + pseudocode for complex algorithms.

- Author: riemac
- Repository: riemac/Skills
- Version: 20260120052549
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/riemac/Skills
- Web: https://mule.run/skillshub/@@riemac/Skills~annotations:20260120052549

---

---
name: annotations
description: Annotation and documentation protocol for rapid-iteration projects (“vibe coding”). Enforces Google Docstring Style plus comment-as-contract: consistency with signatures/types, explicit pre/post-conditions, units/frames/conventions, and rich implementation comments. Use Notes with ASCII + pseudocode for complex algorithms.
---

# Annotations (Google Docstring + Comment-as-Contract)
## Core Principles

1. **Google Docstring Style (primary)**
   - Use Google-style sections: `Args`, `Returns`, `Raises`, `Attributes`, `Notes`, `Examples`
   - Docstrings must describe *semantics and contracts*, not restate names

2. **Comment-as-Contract**
   Document anything that can break silently:
   - **Pre/post-conditions**: ranges, shapes, dtype/device, required keys, ordering
   - **Units and conventions**: units, angle conventions, coordinate frames, axis order, quaternion convention, normalization
   - **Determinism & randomness**: seeds, sampling behavior, stochastic branches
   - **Failure modes**: when exceptions raised, undefined behavior, NaN/overflow hazards

3. **Signature/type info and docs must agree**
   - Signature + type hints are source of truth
   - Docs must not contradict; use prose for constraints types can't express

4. **Implementation comments required**
   - Dense, local explanations near the code they justify
   - Optimize for "future you" to modify safely without re-deriving intent

## What Must Be Documented

### Functions / Methods
- One-line summary (imperative mood)
- `Args` for every parameter (meaning + constraints)
- `Returns` for every return value (meaning + shape/unit/convention)
- `Raises` for intentional or common failures
- `Notes` if algorithm is non-trivial, involves math/geometry, has subtle invariants, or has performance/stability considerations

### Classes / Components
- One-line summary + role in system
- `Attributes` documenting state, units/conventions, lifecycle (created/reset/updated)
- Public methods with side effects and invariants

### Config / Schema / CLI
- Each field/flag meaning, default rationale (if non-obvious), units, valid range
- Cross-field constraints (e.g., `min <= max`, mutually exclusive flags)

### Implementation Comments (inside code)
Required when code contains:
- non-obvious transforms or conventions
- branching logic encoding a design choice
- "magic numbers" (thresholds, scalings, epsilons)
- performance hacks (vectorization, caching, preallocation)
- "temporary" logic you might forget to remove

Guidelines: Comments answer **why** + **what invariant** (not narrating obvious operations)

## Templates and Examples

See resource files for detailed templates and Python/IsaacLab examples:
- [Templates](./resources/templates.md) - Function, Class, Config templates
- [Examples](./resources/examples.md) - Python + IsaacLab code examples

## Review Checklist

- Docstrings/comments match signature + type hints
- Constraints documented for non-obvious inputs (range/shape/unit/frame/convention)
- Frames/units/conventions stated wherever transforms occur
- Magic constants justified or replaced by named constants with rationale
- Notes exists for complex algorithms and includes pseudocode
- Implementation comments explain *why* and invariants, not trivial steps
- Documentation updated after refactors (no drift)

## Anti-Patterns

❌ Docstrings only restate names without semantics  
❌ Missing units/frames/conventions where misinterpretation is likely  
❌ Comments narrating obvious operations rather than intent  
❌ Silent assumptions (deg vs rad, axis order, quaternion convention) left undocumented  
❌ Docstrings drifting after signature changes