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
This commit is contained in:
61
docs/rules/code-comments-policy.md
Normal file
61
docs/rules/code-comments-policy.md
Normal file
@@ -0,0 +1,61 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user