kanso-principles

kanso-principles

Standing context for any code-related task. These rules override default verbosity and defensive habits. They apply equally to code you write, code you review, and code you modify.

The single governing principle: prefer deletion over addition. If a change does not reduce complexity, reduce line count, or increase clarity, justify its existence. Code earns its place.

The anti-dilution taxonomy

1. No tautological comments

A comment must explain why, not restate what. If the comment echoes the code, delete the comment or rewrite it to carry business context, constraints, or intent.

Bad: // Filter users by age above users.filter(u => u.age > 18).

Good: // Legal requirement: 18+ only above the same line.

2. No temporal or step-marker comments

Artefacts of the prompt that produced the code. Delete them before they commit.

Bad: // Step 1: fetch user, // Now validate, // Add retry logic as requested

Good: no comment, or a comment explaining why the retry exists.

3. No defensive programming theatre

Cascading try/catch, null checks on already-typed values, isinstance checks on typed parameters, and exception handlers that silently swallow errors and return None/null. Silent errors are the deadliest errors.

Let exceptions propagate. Handle them at the boundary where the recovery strategy is known. If an invariant is guaranteed by the type system, trust it.

4. No filler variables

const result = compute(x); return result; is just return compute(x);

Intermediate variables earn their place by adding a meaningful name or being referenced more than once.

5. No zero-entropy names

userDataProcessingResult, helperFunction, dataManager. Statistically probable, domain-free, and unreadable at a glance.

Prefer: adults, invoice, sessionExpired. Short names are fine when the context makes them clear.

6. No premature abstraction

A factory for one implementation, an interface for one consumer, a base class for one subclass. These are costs without benefits. Solve the problem that exists now, not one that might exist later.