← Use spec sections guides

How to write comments in .sdd files

How-To Use spec sections Beginner 1061022HOWTO-1061022

HOWTO-1061022Use spec sectionsBeginner

This guide shows you how to write comments in SpecDD .sdd files.

Comments are supported, but they are ignored as spec content. That makes them useful for short non-contract notes and dangerous for hidden requirements.

Short answer

Use whole-line comments whose first non-whitespace character is #. Do not use inline trailing comments as comments. Comments do not create requirements, constraints, tasks, references, or write authority. If the line affects behavior, put it in Must, Must not, Tasks, Scenario, Done when, or another real section.

Syntax

Valid comments:

# root comment
  # section comment
      # deeply indented comment

Not an inline comment:

Must:
  Validate input. # This is body text, not a comment.

Rules:

Steps

1. Use comments for non-contract notes

Acceptable:

# Temporary note: compare this spec with the storage ADR during review.
Spec: Itinerary

Better for durable context:

References:
  /docs/adr/storage-boundary.md

2. Put requirements in sections

Do not write:

# Must reject missing place names.
Spec: Itinerary

Write:

Spec: Itinerary

Must:
  Reject itinerary items without a place name.

3. Put tasks in Tasks

Do not write:

# Note: add missing-place validation later.

Write:

Tasks:
  [ ] Add missing-place validation.

4. Avoid inline comments

This line is a Must body entry with # text inside it:

Must:
  Reject empty place names. # required by support

If the note matters, rewrite the entry or use a separate whole-line comment.

Common mistakes

How to verify the result

Comments are safe when:

← Use spec sections guides