|
|
@@ -162,7 +162,10 @@ guidelines. Optimising for that reader is not optional polish. Concretely:
|
|
|
commentary to explain its flow, split it until the code explains itself.
|
|
|
- **Names that say what they mean.** `_seed_room` beats `do_init`; a boolean
|
|
|
reads as a question (`is_seen`, `retryable`). No single-letter names outside
|
|
|
- throwaway loop variables.
|
|
|
+ throwaway loop variables. Locals earn their line the same way: keep them
|
|
|
+ when they narrow, transform or get reused across branches; drop them when
|
|
|
+ they only re-alias a typed attribute (`asset_id = asset.id` reads inline
|
|
|
+ just as well).
|
|
|
- **Comments explain why, not what.** The code already says what happens;
|
|
|
the comment earns its line by recording intent, constraints, or the bug a
|
|
|
guard exists to prevent (see `adapter.py` for the house style).
|