30 Architectural Principles for Software Engineers

Srinath, a scientist, software architect, and distributed systems programmer, co‑founder of Apache Axis2 and member of the Apache Software Foundation, authored this list of thirty architectural principles.

Basic Principles

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

Principle 2: YAGNI (You Aren’t Gonna Need It) – don’t build unnecessary features; implement them only when needed.

Principle 3: Crawl, walk, run – first get it working, then improve, then make it great; iterate with two‑week milestones.

Principle 4: Automated testing is the only way to create stable, high‑quality products; consider automation in every design.

Principle 5: Always consider ROI – ensure effort is worthwhile.

Principle 6: Understand your users and balance what you need to do; don’t spend months building a DevOps UI if users prefer CLI. This is a concrete expression of Principle 5.

Principle 7: Design and test a feature to be as independent as possible; independence simplifies long‑term maintenance and release.

Principle 8: Avoid unnecessary flashiness; over‑engineered features often go unused.

Feature Selection

Principle 9: Embrace MVP (Minimal Viable Product) – build a few core scenarios, release, then iterate based on feedback.

Principle 10: Implement as few features as possible; if in doubt, omit or remove them, leaving only extension points.

Principle 11: Defer work until someone asks for it, unless it affects core processes.

Principle 12: Have the courage to say no to customers, propose better solutions; remember Henry Ford’s quote about not asking for faster horses.

Server Design and Concurrency

Principle 13: Understand how a server works from hardware to OS to language; optimize I/O calls.

Principle 14: Know Amdahl’s law; shared mutable data slows programs. Use concurrent structures only when necessary and hold locks for minimal time.

Principle 15: In non‑blocking, event‑driven architectures, never block threads or perform I/O in them.

Distributed Systems

Principle 16: Stateless systems are scalable and straightforward; avoid stateful designs that hinder scaling.

Principle 17: Exactly‑once message delivery is hard; aim for lightweight systems and understand trade‑offs.

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

Principle 19: Know the CAP theorem; distributed transactions are difficult; prefer compensation mechanisms; RDBMS transactions don’t scale.

Principle 20: Distributed consistency doesn’t scale; practical node limits are around eight.

Principle 21: In distributed systems you can’t avoid latency and failures; design for failure while considering SLA requirements.

User Experience

Principle 22: Understand your users, their goals, expertise level, and CS knowledge; geeks like extensibility, developers want examples, regular users want UI.

Principle 23: The best product needs no manual.

Principle 24: When stuck between choices, don’t expose the dilemma as a configuration option; provide sensible defaults or automated choices.

Principle 25: Always provide reasonable default values for configurations.

Principle 26: Poorly designed configs cause confusion; always include example values.

Principle 27: Config values must be understandable and directly settable; e.g., ask for max cache memory instead of number of entries.

Principle 28: Throw errors on unknown config inputs; never silently ignore them.

Hard Questions

Principle 29: New programming languages rarely simplify things; don’t switch languages lightly.

Principle 30: Complex drag‑and‑drop UIs are hard; avoid unless you have a large team.

Conclusion

As an architect, act like a gardener—prune, guide, and discuss rather than dictate; use this principle list as an anchor for discussions and a learning path for junior architects.