# Code comments - write WHY, not WHAT

**Binding** for all source files: Python, SQL, SPARQL, PowerShell, YAML, shell.

## Rule

Default to **no comment**. Add one only when the *why* is non-obvious from
the code. If removing the comment wouldn't confuse a future reader, delete it.

A comment earns its place when it captures something the code can't:
hidden constraint, ordering invariant, workaround for a named bug, vendor
quirk, cross-file invariant the type system can't enforce.

## Delete on sight

```python
# Read the manifest file
manifest = read_manifest(csv_root)          # function name says it
```

```python
# Increment counter
counter += 1                                # pure restatement
```

```python
# Added for the benchmark rework (see task 09)
def run_cell(...):                          # belongs in commit message, rots in code
```

```python
# TODO: refactor later
                                            # no owner, no trigger - decoration
```

## Keep

```python
# Q5 must scan raw friction_cycles - track_summary is forbidden for this
# query in every format (spec 08); do not "optimize" this into the summary.
```
Cross-file invariant a refactor must preserve.

```python
# Column order matches MANIFEST.csv writer in generate_data.py - keep in sync.
```
Cross-file invariant the type system can't enforce.

```sql
-- BRIN, not b-tree: cycle values are physically ordered within each
-- partition, so BRIN gives the same pruning at ~1% of the index size.
```
Non-obvious engineering decision with a reason.

## Length

Inline: one line. Block: 1-4 lines. If you need more than a paragraph,
the right home is a rule or spec doc - link it from a one-line comment.

Stale comments are worse than missing ones. When you touch a file, fix or
delete comments whose *why* no longer holds.