Helping your team succeed

Practice · Chapter 6

Overview

A core goal of the architect is to help the team succeed. Four practices covered here: unit testing, easy development-environment setup, pair programming, and reviewing deliverables.

Unit testing

• Testing the smallest testable units (usually methods) to confirm they work. Decompose functionality into discrete, testable behaviors. If the org isn’t already doing it, the architect should institute it — test early and often (an agile practice).
• Loosely coupled code from DRY, SoC, SRP, and Dependency Injection is what makes code unit-testable in isolation.

Benefits: catches defects before check-in/build; ideal for automation in a build process (see DevOps practices); eases debugging (narrows bugs to recent changes); serves as living documentation.

Properties of a good unit test

Property	Meaning
Atomic	Tests a single assumption about a small behavior (usually one method); multiple tests per unit
Deterministic	Same result every run when code is unchanged
Automated & repeatable	Runs unattended as part of the build
Isolated & independent	Runs in any order, alone; depends on nothing but the class under test — no DB, hardware, files, or network. Mock dependencies
Easy to set up	Hard-to-write tests are a code smell about the design or the test
Fast	Large suites must not slow development or builds

The AAA pattern

Organize each test into three sections:

• Arrange — set up preconditions, inputs, and mock objects.
• Act — invoke the method under test (the System Under Test / SUT).
• Assert — verify the results match expectations.

Naming conventions

• Tests are intention-revealing documentation, so use consistent, meaningful names.
• Class: name after the SUT — e.g. OrderService → OrderServiceTests.
• Method: encode method + condition/input + expected result — e.g. CalculateShipping_NullOrder_ThrowsArgumentNullException.

Coverage and upkeep

• Code coverage measures how much source is exercised by tests; aim high, but a percentage only shows which paths ran at least once — it ignores the range of input values, so extra tests are often needed for important scenarios.
• Keep tests up to date as requirements and features change; run all tests after changes to catch unintended consequences.
• Bugs should only be found once: when fixing a bug, add tests reproducing that scenario so the knowledge is captured and the bug can’t silently return.

Setting up development environments

• Minimize the time to get a new/relocated developer productive; setup shouldn’t be harder than necessary.
• Smooth the whole path: access grants, installing tools, pulling latest code from version control, compiling, and running. Tools exist to image/deploy physical and virtual dev machines.
• Beware tribal knowledge — undocumented config tweaks known only to a few. Capture it.

Provide a README

Every project should ship a README covering: a brief project description; software/tools to install (with locations, license keys); special configuration (e.g. pointing at a database); how to connect to version control; a creation date / target version number; licensing info; and contact for help.

Pair programming

• Two developers on one deliverable: the driver codes, the navigator observes; roles rotate on an interval or as they see fit. Both stay active participants.

Benefits:

• Better code quality — a second set of eyes; the driver is more careful when watched.
• Knowledge and skill transfer; spreads coding standards; acts as informal training (great for pairing an architect/senior with a junior).
• Familiarity with the codebase and collective ownership — rotate pairs to spread knowledge widely.
• Keeps the architect out of the “ivory tower” and immersed in the code.

When to use: not all-or-nothing. Apply when there’s a reason — complementary skillsets or a learning opportunity — rather than for trivial tasks.

Reviewing deliverables

Completed deliverables should be reviewed for correctness and problems. Build a positive review culture focused on finding defects, learning, and communication — not blame. Three methods:

Code reviews

• Peer evaluation of code changes to find technical and business-logic defects, enforce coding standards, and spot improvements.
• Typical flow: author requests review → reviewers accept/decline → discussion/feedback → defects recorded and assigned (usually to the author) → fixes tested.
• The architect should stay involved to some degree.
• Don’t review too much at once — effectiveness drops sharply past ~500 lines of code. A checklist of recurring past issues helps; record found defects so they aren’t lost. Related to reviewing software architectures.

Formal inspections

• A structured, scheduled group review — highly effective at finding defects. Roles:
  • Leader/moderator — facilitates, keeps pace, follows up on action items, reports.
  • Author — created the deliverable; limited role, clarifies and explains apparent (non-)defects.
  • Reviewer(s) — prepare beforehand, bring notes, give positive and negative feedback; should be technically competent.
  • Recorder/scribe — records defects and action items (not the moderator or author).
• Focus on finding defects, not solving them. Produce an inspection report; log defects to a backlog/owner; moderator follows up.

Walkthroughs

• Informal: the author guides reviewers through the deliverable; no assigned roles beyond host/author. Flexible format.
• Focus is finding potential defects (the group may optionally suggest changes). Management shouldn’t attend, to avoid influencing it.
• Less effective than other methods, but allows more, and more diverse, reviewers at once.

Citations

• Software Architect’s Handbook (Packt, 2018), Ch.6 “Helping your team succeed”, pp. 461-492.