Learning · Software Engineering Manifesto
Software Engineering Manifesto
This manifesto is a working checklist, not a slogan wall. It is for future teammates (and present ones) deciding how to design, implement, and ship services.
Each note states a principle, then therefore we practice…, then smells that mean we are drifting. The ideas are universal: they do not name a language, cloud, or broker. Deeper how-tos live in the other Learning series.
v1 focus: distributed systems and service design — the failure modes that hurt users when teams move fast.
Add or amend principles as we learn. Prefer short, enforceable language over essays.
Topics
- Own clear boundaries
Every capability has one owner for behavior and data — independence starts with the cut, not with the deployable count.
- Do not hold transactions across the network
A local transaction ends before remote calls — no REST, RPC, or broker send inside an open DB transaction.
- Publish reliably, consume idempotently
Dual-writes lie — durable outbox (or equivalent) for facts; consumers must tolerate duplicates and replay.
- Make failure explicit
Timeouts, budgets, and degradation are design — infinite waits and blind retries are not resilience.
- Sync when you must, async when you can
Request/response only when the caller needs the answer now — otherwise publish facts and decouple.
- Contracts are real APIs
Endpoints and events are commitments — version, compatibility, and ownership beat informal JSON.
- Observability is part of done
Structured logs, metrics, and traces ship with the feature — not as a follow-up ticket after the outage.
- Measure what users feel
KPIs and SLIs track user journeys — vanity infrastructure metrics do not replace a reliability contract.
- Ship small, reversible change
Prefer incremental, roll-backable delivery — expand/contract, flags, and progressive exposure over big-bang releases.
- Keep app processes disposable
Stateless compute, stateful backing services — local memory and disk are not the system of record.
- Limit blast radius
Isolate failure — least privilege, quotas, and defaults that fail closed between services.
- Prefer simple over clever
Clarity beats premature abstraction — complexity must pay rent in real requirements.