30 Architectural Principles for Software Architects

Basic Principles

Principle 1: KISS (Keep it simple, stupid) – Keep everything as simple as possible and solve problems with the simplest solution.

Commentary: Simplicity often requires more thought and time to achieve clear, understandable code.

Principle 2: YAGNI (You Aren’t Gonna Need It) – Do not implement features that are not currently needed.

Commentary: Avoid speculative development that leads to unnecessary code bloat.

Principle 3: Crawl, walk, run – First get a working version, then iteratively improve and optimize.

Principle 4: Automated testing is the only way to create stable, high‑quality products; aim to automate everything.

Commentary: Testing is essential, though there is no single universal standard.

Principle 5: Always consider ROI – only implement what is worthwhile.

Principle 6: Understand your users and balance work accordingly; avoid building UI that users won’t use.

Commentary: Question whether you are solving real user problems or just using new technology for its own sake.

Principle 7: Design and test features to be as independent as possible.

Principle 8: Avoid flashy, unused features; keep the architecture lean.

Commentary: Simplicity in communication is key.

Feature Selection

Principle 9: Embrace MVP – build a minimal viable product, release it, and iterate based on feedback.

Principle 10: Implement as few features as possible; remove or defer doubtful ones.

Principle 11: Only build features when there is a concrete need, unless they affect core processes.

Principle 12: Have the courage to say no to customers and propose better solutions; remember that experts should guide, not just follow trends.

Server Design and Concurrency

Principle 13: Understand how a server works from hardware to OS to language; minimize IO calls.

Principle 14: Know Amdahl’s law; use concurrent data structures only when necessary and keep lock hold times short.

Principle 15: In non‑blocking, event‑driven architectures, never block threads with IO.

Distributed Systems

Principle 16: Stateless systems are scalable; avoid stateful designs that hinder growth.

Principle 17: Strive for exactly‑once delivery, though it is hard; aim for lightweight systems.

Principle 18: Make operations idempotent to simplify recovery and support at‑least‑once delivery.

Principle 19: Understand CAP theorem; distributed transactions are difficult, prefer compensation mechanisms.

Principle 20: Distributed consistency does not scale well; limit cluster size (e.g., 8 nodes).

Principle 21: Latency and failures are inevitable in distributed systems.

User Experience

Principle 22: Know your users, their expertise level, and preferences (e.g., UI vs CLI).

Principle 23: The best product needs no manual.

Commentary: Some documentation (release notes, hardware specs) remains necessary.

Principle 24: When undecided, avoid exposing raw configuration choices to users; provide sensible defaults.

Principle 25: Always set reasonable default values for configurations.

Principle 26: Provide example values for poorly designed configurations.

Principle 27: Configuration values must be understandable and directly editable by users.

Principle 28: Throw errors on unknown configuration values; never silently ignore them.

Hard Problems

Principle 29: New languages rarely simplify development; switching languages should be done cautiously.

Principle 30: Complex drag‑and‑drop UIs are costly; only attempt them with large teams.

Conclusion

Architects should act as gardeners—pruning and guiding rather than dictating—facilitating discussion, providing defaults, and using these widely accepted principles as anchors for learning and decision‑making.