Engineering guide / Software quality
Make the next change easier to understand and verify.
Consistent code helps people work together. It does not establish that a feature behaves correctly, fits the system or can be operated safely. Maintainable software needs a connected set of practices: clear rules, explicit design decisions, thoughtful review, useful tests and feedback from the running service.
Different checks, different questions
A clean build is useful evidence with a limited scope.
Imagine adding order cancellation to an existing application. A formatter can normalize the new code. Types can check declared contracts. Neither decides who may cancel, what happens after dispatch, or how a repeated request affects the order. Those questions need explicit behavior, design and verification.
- Consistency supports comprehension
- Shared naming and formatting rules reduce avoidable variation. They make a change easier to read, but cannot decide whether its business rule is correct.
- Correctness depends on the requirement
- A test can faithfully confirm the wrong expectation. Review the intended behavior and meaningful exceptions before treating a passing assertion as acceptance.
- Maintainability includes future work
- Another person needs to understand the decision, locate the affected behavior, change it and check the result. Documentation and usable tests are part of that work.
Six connected quality practices
Give every practice a purpose and an evidence boundary.
For the illustrative cancellation change, each practice addresses a different source of uncertainty. Select depth according to the actual consequence of an error.
Conventions that people can apply
01Quality question: Can another contributor read this without decoding a new style?
- Purpose
- Naming, structure and formatting rules give contributors a shared way to express ordinary code.
- Starting evidence
- The repository's written conventions, existing patterns and configured automated checks.
- Apply it to the change
- Use the established names and structure for the cancellation code. Automate objective style rules where practical and separate unrelated formatting from behavior changes.
- Responsible judgment
- Maintainers decide the local convention and distinguish required rules from personal preferences.
- Evidence produced
- A readable diff and results from the relevant formatter, linter or static checks.
- Does not prove
- That cancellation is permitted in the right circumstances or that every runtime value is valid.
- Maintenance value
- Later contributors can focus on the behavior instead of relearning presentation conventions.
Design decisions with their reasons
02Quality question: Where should this rule live, and what else depends on it?
- Purpose
- A consequential decision about boundaries, state or interfaces needs a rationale that survives the original author.
- Starting evidence
- Current data ownership, dependent consumers, alternatives and constraints that shaped the choice.
- Apply it to the change
- Decide where cancellation state is authoritative and how other components learn about it. Record a significant tradeoff rather than only drawing the final component diagram.
- Responsible judgment
- The technical owner and affected teams assess the boundary and its consequences.
- Evidence produced
- A decision record with context, chosen approach, consequences and status.
- Does not prove
- That the implementation follows the decision or that a previously accepted design remains suitable forever.
- Maintenance value
- A future change can revisit the original constraints. Preserve the old decision when a new one supersedes it.
Review that challenges the behavior
03Quality question: Does this change solve the intended problem without avoidable complexity?
- Purpose
- A reviewer examines meaning, system fit and cases that automated checks may not express.
- Starting evidence
- The intended cancellation behavior, the diff, relevant surrounding code and verification results.
- Apply it to the change
- Trace an allowed cancellation and a rejected one. Ask how repeated requests, concurrent updates and downstream effects are handled where those situations apply.
- Responsible judgment
- A reviewer with relevant expertise assesses the change; product owners resolve ambiguous business behavior.
- Evidence produced
- Resolved review questions, accepted tradeoffs and identified follow-up work.
- Does not prove
- That every execution path has been exercised or that an unfamiliar specialist concern has been assessed.
- Maintenance value
- Review spreads understanding and catches choices that would make subsequent changes harder.
Tests that would detect the wrong result
04Quality question: Which failure would this test actually catch?
- Purpose
- Checks express expected behavior and guard important boundaries at an appropriate level.
- Starting evidence
- Acceptance examples, known failure modes, real interface contracts and the behavior of dependencies.
- Apply it to the change
- Check cancellation eligibility in focused tests, persistence at the data boundary and a critical user flow where appropriate. Ensure a deliberately wrong result would fail the relevant assertion.
- Responsible judgment
- Engineers choose useful coverage; reviewers assess whether the tests exercise the requirement.
- Evidence produced
- Repeatable results tied to the behavior, with skipped or unavailable checks stated.
- Does not prove
- That a mock matches the deployed dependency, every input was covered or a coverage percentage equals quality.
- Maintenance value
- A later refactor can reveal a changed contract before the change is accepted.
Release and operating evidence
05Quality question: Will the tested change work in the environment that receives it?
- Purpose
- Configuration, deployment sequence and service behavior can differ from a developer's test environment.
- Starting evidence
- The release artifact, configuration, dependency versions, operating responsibilities and recovery approach.
- Apply it to the change
- Check the cancellation change in the intended release context. Define how the authorized operating team will detect an unexpected result and respond.
- Responsible judgment
- The release and service owners decide readiness and manage any live observation or recovery.
- Evidence produced
- Environment-specific checks, release decision, monitoring signals and a usable response plan.
- Does not prove
- That a successful local test is production proof or that an uneventful limited rollout exposes every rare fault.
- Maintenance value
- The team can connect a reported problem to the released change and its operating conditions.
Learning that improves the next change
06Quality question: What should become easier or more explicit after this work?
- Purpose
- Review findings and actual defects reveal missing knowledge, checks or ownership.
- Starting evidence
- The resolved issue, its cause, affected behavior and evidence of the correction.
- Apply it to the change
- If cancellation can be repeated incorrectly, repair the behavior and add a relevant regression check. Update the explanation or decision record when the old one is misleading.
- Responsible judgment
- Maintainers prioritize the improvement and verify that it addresses the actual cause.
- Evidence produced
- A corrected behavior, useful regression protection and current supporting documentation.
- Does not prove
- That adding more rules or tests automatically resolves the underlying problem.
- Maintenance value
- Future contributors inherit the lesson through the code and its evidence, rather than relying on someone remembering the incident.
Read the result precisely
What does a green check actually establish?
These examples are deliberately narrow. A result supports the behavior and environment it exercised, not every claim someone might attach to it.
| Evidence | Can support | Cannot establish alone | Review judgment | Cancellation example |
|---|---|---|---|---|
| Formatting and lint | Configured rules pass | Business correctness | Rule suitability | Consistent names and structure |
| Type checking | Declared contracts fit | All external input is valid | Boundary validation | Allowed state representation |
| Design record | Reason for a decision | Implementation conforms | Current tradeoffs | Authoritative state owner |
| Behavioral tests | Selected expectations hold | Complete requirement coverage | Useful assertions | Reject cancellation after dispatch |
| Review | Inspected design and logic | All runtime paths pass | Relevant expertise | Repeated request semantics |
| Operating checks | Observed release behavior | Every future condition | Exposure and response | Detect unexpected order states |
Review one complete change
Connect the requirement to the evidence.
Use a real change to assess quality practices. A list of tools is less informative than seeing how a team makes and verifies a decision.
- 01
Describe the behavior
State the intended result and important exceptions. For cancellation, identify allowed states, authorized actors and effects on connected work.
- 02
Locate the boundary
Find the code, data and interfaces that own the behavior. Check whether a design decision or compatibility promise constrains the change.
- 03
Implement a readable change
Follow established conventions and keep the diff coherent. Explain a necessary tradeoff instead of introducing speculative abstractions.
- 04
Verify at the right levels
Choose checks that address the failure modes. Review their assertions, the actual user behavior and any environment-specific limits.
- 05
Preserve the handover
Record unresolved work, operating responsibilities and any changed build or release instructions. Leave the next contributor a usable account of what was established.
Keep the standard useful
Improve code health without turning polish into a barrier.
A standard should help people make sound changes. It needs room for engineering judgment and a clear distinction between a required correction and a preference.
- Separate requirements from preferences
- Make mandatory conventions explicit. Explain correctness or design objections through evidence; label optional polish so it does not obscure a consequential issue.
- Keep exceptions visible
- When an urgent change leaves work behind, record the reason, affected risk and follow-up owner. An exception should not silently become the normal standard.
- Maintain the checks themselves
- Remove misleading assertions, investigate flaky results and keep test setup understandable. A check that the team routinely ignores provides weak evidence.
- Match review to expertise
- A familiar code style does not make every reviewer qualified for every concern. Bring in the relevant expertise when a change affects a specialized boundary.
Questions about software quality
Ask about the method behind the result.
Useful answers connect an engineering practice to the behavior it protects and the uncertainty it leaves.
- Are coding standards just formatting rules?
- They can include naming, structure and local engineering conventions. Formatting is the easiest part to automate. Design, business behavior and operating readiness still need their own evidence and judgment.
- Does high test coverage mean the software is good?
- Coverage describes code reached under a particular measurement. It does not establish that assertions are meaningful, requirements are correct or external systems behave like test doubles. Inspect representative tests and their limits.
- Should every change need an architecture document?
- No. Reserve a decision record for a significant choice whose context and consequences future contributors need. Routine edits can use the existing decision and explain their purpose in the change description.
- Should reviewers require perfect code?
- Google's review guidance favors changes that improve overall code health without requiring every optional refinement. That does not justify accepting a known correctness problem or ignoring a requirement relevant to the change.
- What evidence should a buyer request?
- Ask the team to walk through a recent authorized example: the requirement, relevant design choice, review, checks, known gaps and release considerations. Avoid asking for another customer's confidential code or treating a tool list as proof of quality.
Source basis
Sources behind the control model.
- 01
Google Engineering Practices
The Standard of Code ReviewGuidance balances progress with improving code health, distinguishes technical evidence from preference and rejects perfection as a routine approval requirement.
- 02
Google Engineering Practices
What to look for in a code reviewReview criteria cover design, functionality, complexity, useful tests, naming and documentation. The article's cancellation example is illustrative, not a case from this source.
- 03
AWS Prescriptive Guidance
Architectural decision record processDescribes decision context, consequences, ownership and review. Accepted decisions are preserved and superseded through a new decision when the approach changes.
- 04
Google SRE
Testing for ReliabilityThe sections on test limits, traditional test layers and production configuration explain why passing tests alone do not establish reliability. Operational examples require their own environment and authority.
Start with one real workflow
A Systems Audit is the usual starting point. If the opportunity is already clear, we can move directly into a focused build.
Show Us the WorkflowStart with the free automation readiness checklistOBSERVEQUANTIFYDECIDEBUILD