Files

administrator b173ac82a9 fix(docs): fix formatting issues in README.md

- adapt meta-/code-/obs- rules to the local Python benchmark pipeline
- replace db-sql-ddl, code-config-env-scope, test-e2e-pytest with pipeline equivalents
- add code-python-style, data-determinism, data-naming-units, bench-methodology, build-pipeline-tasks
- normalize specs and README typography to ASCII per code-data-formatting
- rewrite root CLAUDE.md trigger table; add .cursorrules and .gitignore
- specs: pipeline plan and task specs 00-11
- rules: 19 binding rule files adapted for this project
- docs: CLAUDE.md rule-trigger table
- config: .cursorrules commit convention, .gitignore excluding out/ and .venv/
- docs: rewrite README.md with pipeline diagrams, setup guide, result placeholders
- config: requirements.txt for the closed dependency list
- datagen: make_lab_config.py writes out/config/lab_config.yaml and .done marker

2026-07-11 13:39:13 -04:00

1.8 KiB

Raw Blame History

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

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

# Increment counter
counter += 1                                # pure restatement

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

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

Keep

# 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.

# Column order matches MANIFEST.csv writer in generate_data.py - keep in sync.

Cross-file invariant the type system can't enforce.

-- 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.

1.8 KiB Raw Blame History