better-maintainability

Make local code predictable to read and change

Reduce the amount of state, context, and control flow a maintainer must hold in mind. Preserve cohesive narratives and established domain language.

Own the local implementation

Own findings inside functions, classes, modules, and cohesive components: naming, control flow, state, side effects, abstraction level, responsibility, and local change cost.

Escalate cross-module dependency problems to better-architecture, repeated knowledge to better-duplication, and unnecessary layers or speculative generality to better-simplicity.

Review workflow

1. Follow behavior, not metrics

Trace representative inputs through state changes, branches, effects, errors, and outputs. Identify what a maintainer must know to make a safe change.

Use complexity scores, function length, nesting depth, parameter count, and lint warnings only to locate code worth reading. Never report a threshold violation without demonstrating impact.

2. Inspect comprehension risks

Investigate:

• functions or classes with unrelated reasons to change;
• deeply nested conditionals that hide the primary path;
• control flow distributed across callbacks, flags, exceptions, or mutable state;
• hidden I/O, global mutation, time, randomness, or logging in apparently pure operations;
• names that conceal domain meaning, units, state, or side effects;
• mixed abstraction levels, such as policy decisions interleaved with serialization details;
• magic values whose meaning or ownership is unclear;
• booleans or enums that permit invalid combinations;
• broad exception handling that loses context or continues in an invalid state;
• order-dependent methods or partially initialized objects;
• comments that compensate for misleading structure or have drifted from behavior;
• dead paths, stale compatibility branches, or unused parameters;
• APIs whose return or mutation behavior surprises callers.

A long linear function can be clearer than ten tiny helpers. A short function can still hide dangerous state. Judge the reading and change path.