Local Reasoning and Refactoring

Refactoring rules cover local reasoning, concept helpers, visible linear stories, side-effect loops, whitespace paragraphs, DRY pressure, and weak abstractions.

Local reasoning, reader burden, concept helpers, and abstraction pressure.

9 rules

Change ShapeOwnershipBoundary CorrectnessAlign Seams with Real VariationREFACTORING-ALIGN-SEAMS-WITH-REAL-VARIATIONPut abstraction seams where code already varies across backends, policies, protocols, tests, or ownership boundaries. Avoid adding names and jumps for hypothetical futures unless the next change or risk clearly justifies them.Reader LocalityChange ShapeOwnershipDo Not Over-apply DRYREFACTORING-DO-NOT-OVER-APPLY-DRYKeep similar-looking code separate until it has the same meaning and changes together. Premature sharing can couple unrelated policies and make later edits harder.Reader LocalityChange ShapeOwnershipExtract Concept HelpersREFACTORING-EXTRACT-CONCEPT-HELPERSExtract helpers when the new function names a real concept boundary with a stable purpose. Hiding a few lines behind a weak name adds a jump without reducing the readers burden.Reader LocalityChange ShapeKeep Linear Story VisibleREFACTORING-KEEP-LINEAR-STORY-VISIBLEKeep simple ordered workflows inline when the sequence is the clearest explanation. Extract only the substeps that carry their own concept, policy, reuse, or test surface.Reader LocalityChange ShapeOwnershipKeep Weak Abstractions CloseREFACTORING-KEEP-WEAK-ABSTRACTIONS-CLOSE-TO-THEIR-USEKeep tentative helpers, types, or traits near their first use until the boundary proves itself. Local placement makes weak abstractions easier to revise, inline, or delete before other modules depend on them.Boundary CorrectnessValidation PolicyReader LocalityMake Edge Cases ExplicitREFACTORING-MAKE-EDGE-CASES-EXPLICITName boundary behavior near the branch, calculation, or return that depends on it. This makes policy reviewable and shows when stronger types should prevent invalid states instead.Reader LocalitySide EffectsChange ShapePrefer Local ReasoningREFACTORING-PREFER-LOCAL-REASONINGShape code so relevant state, invariants, and effects are visible near the change. Centralize only when it reduces total reasoning, because distant reconstruction raises cognitive load and error risk.Side EffectsReader LocalityChange ShapePrefer Loops for Side EffectsREFACTORING-PREFER-LOOPS-FOR-SIDE-EFFECTSUse ordinary loops when the main purpose is mutation, I/O, logging, or other side effects. Iterator chains are better for value transformation; using them for effects can hide order, early exits, and error handling.Reader LocalityLocal ConventionsChange ShapeUse Whitespace as Function ParagraphsREFACTORING-USE-WHITESPACE-AS-FUNCTION-PARAGRAPHSUse blank lines to group related statements inside a function before extracting more names. Paragraph-like spacing can reveal the local story while avoiding unnecessary helper jumps.