The software engineering process

#SDLC: match the lifecycle to the risk

Coding sits within a broader lifecycle: understand needs, design, implement, verify, deploy, operate and improve. That is the SDLC. The useful question is how to expose wrong assumptions early and deliver operable value.

A process can be both iterative and incremental, and Agile delivery can include formal approvals. Match feedback gates to risk rather than applying identical ceremony to every change.

#The Agile manifesto in practical terms

Agile does not eliminate plans or documentation. Its four values guide trade-offs:

1. Let people collaborate to solve problems, supported by tools and process.
2. Use working software to test value; documents explain and support it but do not establish usefulness.
3. Work with customers as understanding evolves; a contract cannot replace that conversation.
4. Revise plans when evidence changes; planning is continuous.

In practice: deliver a small slice, demonstrate it, gather feedback, measure outcomes and decide what comes next. Technical excellence and tests make adaptation safer. More meetings or daily priority changes do not establish agility. Reference: Agile manifesto.

#Scrum accountabilities, events and artifacts

Scrum provides a cadence for inspection and adaptation around a goal. The Scrum Team has a Product Owner accountable for maximizing value and ordering the Product Backlog, a Scrum Master accountable for Scrum's effectiveness, and Developers accountable for planning the work, quality and the Increment. Project manager is not a formal Scrum accountability, although an organization may employ one.

Refinement is ongoing activity, not an additional formal event. The Review is not a release gate; a Done Increment can ship before Sprint end. Do not turn the Daily into a management status report. Reference: Scrum Guide 2020.

#Scrum, Kanban, Ready and Done

If a team starts more than it finishes, a board alone will not fix delivery. Kanban makes workflow and policies explicit and controls work in progress, allowing new work to be pulled when capacity exists.

Definition of Ready: an optional team agreement, not a formal Scrum element. It might require a clear purpose, example acceptance criteria and known dependencies. Avoid turning it into a handoff gate that prevents learning.

Definition of Done: shared Increment quality criteria covering appropriate tests, review, risk-based security checks, documentation, observability and deployment readiness. Acceptance criteria describe one item's behavior; DoD applies across the work.

Cycle time runs from work start to finish; lead time may start at request, depending on team definitions. Throughput is completed items per period; work item age measures unfinished work. Little's Law states average WIP = throughput rate × average cycle time for a stable system with consistent boundaries and units; it does not promise one item's completion date.

#Requirements, user stories and acceptance criteria

Before choosing an endpoint or database, identify who needs what and why. A functional requirement specifies behavior such as cancelling an order. A quality attribute makes qualities such as latency, availability or accessibility measurable; “fast” alone is not verifiable.

A user story emphasizes a user and value: “As a customer, I want to cancel an order before shipment so I do not wait for an unwanted product.” Not every task needs that template; a spike or platform upgrade can use a direct description. Slice work vertically by value rather than delivering a database Sprint followed by a UI Sprint.

Story: Customer cancels an order before dispatch.
(1) Given a paid order that has not been dispatched
    When its owner cancels it
    Then the order is cancelled and one refund request is recorded
(2) Given an order already dispatched
    When its owner requests cancellation
    Then cancellation is rejected without a refund request
(3) Quality target for this example:
    p95 cancellation API latency below 300 ms at 100 requests/second
    measured in a production-like load test, excluding refund settlement

Confirm examples with product, QA and stakeholders; Given/When/Then does not require a BDD tool. Resolve conflicting requirements before implementation.

#Estimation: size and uncertainty, not a promise

People need forecasts to plan, but an exact number before understanding the work hides uncertainty. Story points are a team-agreed relative measure of size, complexity and uncertainty, not hours. T-shirt sizes such as S, M and L help early grouping.

1. Choose a shared reference item and discuss assumptions and dependencies.
2. In planning poker, estimate independently and reveal together; differences expose missing information.
3. Split large items and use a timeboxed spike for a specific technical question.
4. Provide a range with confidence and assumptions, then update it using observed data.

Do not convert points into hours or compare velocity across teams. Calendar time includes queues, review and approvals. Use your team's throughput, cycle-time distributions and history for probabilistic forecasting, explaining that history is not a guarantee when the work changes.

#Design documents and ADRs: record the reasoning

A consequential technical choice deserves review before thousands of lines depend on it. A design document explains the problem, requirements, alternatives, data flow, risks and rollout. A compact ADR records one decision, its context and consequences so future readers can revisit it with evidence.

Design doc
Problem and desired outcome:
Scope and non-goals:
Functional requirements and measurable quality attributes:
Options considered and trade-offs:
Proposed interfaces, data ownership and failure behavior:
Security, observability and operating cost:
Migration, rollout, rollback and validation:
Open questions, owner and review date:

ADR-007: Record invoice notifications in a transactional outbox
Status: Accepted
Context: A crash between database commit and send can lose a notification.
Decision: Commit the notification record with the invoice transaction.
Alternatives: Direct send; distributed transaction.
Consequences: Eventual delivery, duplicate handling and dispatcher operations.
Revisit when: Delivery requirements or transaction boundaries change.

Use the smallest document appropriate to the decision. Link the PR, diagrams and measurements, and explain rejected alternatives. If a decision changes, supersede the old ADR with a new one rather than erasing history. Avoid duplicating implementation details that will drift from code.

#Code review as actionable feedback

Review finds risks and shares knowledge, but does not replace automated checks or design review. A small PR with a clear purpose is easier to review well. Authors explain the problem, behavior change, validation and risks, then review their own diff first.

1. Understand requirements and boundaries, then consider the user-visible behavior.
2. Check correctness, failure paths, security, data compatibility and tests.
3. Separate blockers, suggestions and nits; automate mechanical formatting rules.
4. Give a checkable reason: “This retry could duplicate a charge; can we preserve its idempotency key?”
5. Agree and record the resolution, inspect the final diff and run required checks.

If discussion stalls, talk briefly and summarize the decision in writing. Evaluate code rather than people, and distinguish preference from correctness. Review latency affects flow; reserve capacity to clear queues instead of continually starting more work.

#Make technical debt visible and actionable

Technical debt is future cost created by design or implementation choices made for immediate benefit or under incomplete knowledge. Not every disliked piece of code is debt. Debt may be deliberate and measured, reckless, or discovered through later learning. Useful categories include design, tests, dependencies, operability and documentation.

Debt item: Duplicate invoice status mapping
Evidence: Three recent changes required edits in four places.
Impact: Inconsistent paid status and additional review effort.
Principal: Centralize mapping behind one adapter and characterize behavior.
Interest: Repeated changes and reconciliation incidents.
Owner: Invoicing team
Priority trigger: Before adding another invoice provider
Success measure: One mapping boundary and verified contract examples

Connect debt to change cost or demonstrated risk, with an owner and review date. Pay it down alongside related features or through agreed dedicated work. Compare repair cost with benefit; a rewrite may introduce more risk than the debt. “Clean it up later” needs a recorded item and priority.

#Trunk-based development and feature flags

Long-lived branches delay integration and increase conflicts. Trunk-based development integrates small changes frequently into a deployable trunk, supported by fast CI. It does not require direct pushes: short-lived branches and PR review can support it.

// (1) Evaluate a server-controlled flag for this request/cohort.
bool enabled = featureFlags.IsEnabled("new-invoice-view", userId);
var view = enabled
    ? await newInvoices.GetAsync(id, ct)
    : await currentInvoices.GetAsync(id, ct); // (2)

Deployment moves a version into an environment; release exposes it to users. Flags separate the two and support canaries and kill switches. Assign an owner, removal date and safe default, and never substitute a flag for authorization. Flag combinations increase test cost; remove obsolete paths after stabilization.

#DORA metrics measure the delivery system

Individual commit counts or story points do not measure value. DORA examines delivery speed and safety at the application or service level to expose constraints. The historical four metrics remain common interview material; the current model has five, adding deployment rework rate.

MTTR is an older, broader and potentially ambiguous term; specify definitions rather than mixing all outages with deployment failures. Measure consistent boundaries and inspect distributions and trends. Avoid ranking teams or people, or creating artificial deployments to raise counts. Pair these signals with reliability, user satisfaction and product outcomes. Reference: Current DORA definitions.

#Incidents, stakeholder alignment and living documentation

During an incident, reduce user impact and restore service first. Assign severity, an incident commander to coordinate, responders to investigate and execute, and a communications owner. Record a timeline and decisions. Give regular updates covering known impact, mitigation and the next update time; do not invent a recovery ETA.

1. Detect and triage: establish impact and escalate early.
2. Mitigate: safely roll back, disable a flag or shed load; restoration can precede full diagnosis.
3. Recover and verify: check user journeys and data, not only a health endpoint.
4. Review: record impact, timeline, contributing factors, detection gaps and successes, then assign measurable actions with owners and dates.

Blameless analysis asks why decisions made sense with information available at the time and improves system conditions; accountability and follow-through still matter. “An engineer pressed the wrong button” is insufficient analysis.

With product and stakeholders, clarify outcomes, offer options with costs and risks, and agree scope, quality and decision boundaries. If a deadline is fixed, negotiate scope and rollout rather than concealing risk until the final day.

Documentation stays useful when it has an owner, audience and question to answer. Store runbooks and ADRs with code and update them in the behavior-changing PR. Generate API references from contracts, check snippets and links in CI, and rehearse runbooks. Avoid duplicating one source of truth in three places.