30 Software Architecture Principles for Effective System Design

The author, Srinath, a scientist, software architect, and co‑founder of Apache Axis2, shares thirty architecture principles he has distilled from extensive experience in distributed systems, emphasizing that architects should be team members who guide, discuss, and prune rather than dictate.

Basic Principles

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

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

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

Commentary: Implementing unused functionality leads to code bloat.

Principle 3: Crawl, walk, run – first get something working, then iteratively improve and expand.

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

Commentary: Automation standards vary, but it remains essential.

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

Principle 6: Know your users and balance work accordingly; avoid building elaborate UI for users who prefer CLI.

Commentary: Ask 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 to avoid waiting on unrelated components.

Principle 8: Avoid unnecessary flashy designs; keep solutions simple and directly useful.

Commentary: Simpler communication and design are more effective.

Feature Selection

Principle 9: Embrace MVP (Minimum Viable Product); release a small set of core scenarios, gather feedback, then iterate.

Principle 10: Implement as few features as possible; if uncertain, omit or provide a simple extension point.

Principle 11: Defer work until it is truly needed, unless it impacts core workflows.

Principle 12: Have the courage to say no to customers and propose better solutions; remember Henry Ford’s insight about not asking people what they want.

Server Design and Concurrency

Principle 13: Understand how a server works from hardware to OS to language; reduce the number of I/O calls for optimal architecture.

Principle 14: Apply Amdahl’s Law; share mutable data sparingly, use concurrent structures only when necessary, and keep lock hold times minimal.

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

Distributed Systems

Principle 16: Stateless systems are scalable; avoid building stateful components that hinder expansion.

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

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

Principle 19: Know the CAP theorem; distributed transactions are difficult, so prefer compensation mechanisms over traditional RDBMS transactions.

Principle 20: Distributed consistency does not scale well; practical clusters often limit to around eight nodes.

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

User Experience

Principle 22: Understand your users’ expertise and goals; tailor interfaces (UI vs CLI) accordingly.

Principle 23: The best product needs no manual.

Commentary: Even in agile environments, essential documentation (release notes, hardware specs) remains necessary.

Principle 24: When undecided, avoid exposing complex configuration choices to users; provide sensible defaults and limited options.

Principle 25: Always set reasonable default values for configurations.

Principle 26: Poorly designed configuration leads to confusion; provide example values.

Principle 27: Configuration values must be understandable and directly settable (e.g., use memory size instead of cache entry count).

Principle 28: Reject unknown configuration values with explicit errors; never silently ignore them.

Hard Problems

Principle 29: New programming languages rarely simplify everything; avoid switching languages lightly.

Principle 30: Complex drag‑and‑drop UIs are costly; only attempt them with a large, dedicated team.

Conclusion

Architects should act like gardeners—pruning and guiding rather than dictating—providing a well‑accepted list of principles that serve as anchors for discussion and a learning path for junior architects.