Human Brain Code

Human Brain Code

Core principle

Code is for human brains, not machines.

Assume the reader can only hold about four facts in working memory at once. Prefer local clarity over cleverness, density, or abstraction for its own sake.

Quick start

1. Name multi-part conditions before branching.
2. Use early returns to keep the happy path flat.
3. Remove layers that force the reader to jump around.
4. Comment on why, tradeoffs, and traps, not on what the next line already says.

Workflow

1. Reduce working-memory load

• If a reader must track more than about four facts, split the logic into named intermediate variables.
• Prefer names that carry intent, not implementation details.
• Use self-descriptive values so readers do not need a private lookup table in their heads.

2. Make conditionals readable

• Extract compound boolean logic into intermediate variables with meaningful names.
• Avoid large inline expressions that mix &&, ||, and negation when a name would make the branch obvious.
• Prefer facts like is_valid, is_allowed, has_capacity, and needs_retry.

Instead of:

if val > limit && (condition2 || condition3) && condition4 && !condition5

Prefer:

is_valid = val > limit
is_allowed = condition2 || condition3
is_secure = condition4 && !condition5

if is_valid && is_allowed && is_secure

3. Keep control flow linear

• Prefer early returns for missing, invalid, or exceptional cases.
• Avoid nested if pyramids when guard clauses keep the main path obvious.
• Let the reader spend most of their attention on the default success path.

4. Keep modules proportionate

• Prefer composition over deep inheritance.
• Avoid shallow classes, methods, or modules with large interfaces and tiny behavior.
• Prefer the fewest methods, classes, and modules that still preserve clear ownership, operational clarity, and local comprehensibility.
• Do not create extra layers unless they remove real complexity for the reader.

5. Use comments sparingly and precisely

• Allowed: bird's-eye overview comments, why comments, constraints, invariants, tradeoffs, and explanations of tricky behavior.
• Avoid comments that merely restate the next line of code.
• When code is hard to explain without a long what-comment, rewrite the code first.

6. Use the smallest useful language subset

• Do not overuse advanced language features when simpler constructs are clear enough.
• Prefer familiar, direct forms over compact but mentally expensive ones.

7. Duplicate a little when it helps

• Do not treat DRY as an absolute rule.
• A small amount of duplication is better than hidden coupling, premature reuse, or extra indirection.

Review checklist

• No expression forces the reader to track too many facts at once.
• Complex boolean logic is named before it is used.
• The happy path reads top-to-bottom with minimal nesting.
• Comments explain why, not what.
• Abstractions reduce mental load instead of adding it.
• Names are self-descriptive enough that readers do not need extra mappings to understand the code.