Flexible Coding: First Principles for Scalable Software
·Bryan Lai
Flexible Code: First Principles for Scalable Software
Good code protects the next change.
Bad code makes every change feel like trespassing.
First Principles
Most software advice is trying to control three forces:
- Cognitive load: A person can only hold so much in their head. Good code reduces useless confusion.
- Entropy: Systems rot as they change. Good code slows the rot.
- Change: Requirements will move. Code that assumes a frozen future is already wrong.
Practices
SOLID
- Single responsibility: One module, one reason to change.
- Open/closed: Add behavior without rewriting stable code.
- Liskov substitution: A subtype should work anywhere the parent type works.
- Interface segregation: Do not make callers depend on methods they do not use.
- Dependency inversion: High-level policy should not depend directly on low-level details.
Simplicity
- KISS: Complexity is a liability.
- YAGNI: Do not build features before they are needed.
- DRY: One fact should have one home.
Human Rules
- Least astonishment:
get_user()should not delete a user. - Boy Scout Rule: Leave the code cleaner than you found it.
Good Code Looks Like This
Clear
- Names explain the job.
- Bad:
if (x == 4) - Good:
if (retry_count == MAX_RETRIES)
- Bad:
- Business intent is visible.
- Formatting is boring and consistent.
- Related code stays close together.
Reliable
- Stateless services are easier to scale.
- Idempotent operations are safer to retry.
- Loosely coupled components can change independently.
- Cohesive modules do one job well.
Changeable
- Changing the database should not break the UI.
- Code that is hard to test is usually badly shaped.
- Magic numbers belong in named constants or config.
Checklist for Code Reviews
Ask three questions:
- Can I understand this without asking the author?
- If this requirement changes, what else breaks?
- Is this solving a problem we have now?