WBTechnical excellence

Technical excellence. Measured, not promised.

Software gets expensive when every change breaks something else. These 27 engineering principles are how we keep change cheap, year after year. Each one comes with the questions we use to check that we really follow it.

Groups
4
Principles
27
Each one
measured · 71 check questions
Test feedback
under 20 minutes from commit
Way of working
Scrum · 2-week sprints
01White Box Core Concepts

The principles, one at a time.

Four groups, 27 principles. Pick one to see what it means in concrete terms, how we measure it, and a small diagram of the idea at work.

What we build on
  • Clean Code
  • Clean Architecture
  • Domain-Driven Design
  • Self-testing code
  • Continuous Delivery
  • Agile practices
  • User-focused UI/UX design
What it is for
  • Maintainability
  • Adaptability
  • A smooth user experience
Principle explorer 01 / 27

Core OOP Principles

Object-oriented programming is the base of robust, maintainable software. This group covers polymorphism, inversion of control and encapsulation: what keeps code flexible as it grows.

Core OOP Principles · 1 of 4

Self-testing Code

In concrete terms

Every finished story or task is proven by automated tests. Writing the test first (TDD) is recommended, not mandatory. The proof is not optional.

How we measure it
  • What is the ratio of tests to lines of code?
  • How much of the code do the tests cover?
  • Is writing tests part of the Definition of Done?
Core OOP Principles · 2 of 4

Polymorphism

In concrete terms

We use polymorphism, sensible inheritance and composition, and the Open-Closed principle. Where behaviour varies, each variant gets its own type instead of one more branch in a long if or switch.

How we measure it
  • How is variation in behaviour handled?
  • How many if and switch statements are there?
  • Can behaviour be extended without changing existing code?
Core OOP Principles · 4 of 4

Encapsulation

In concrete terms

Every member gets the minimum visibility it needs: as private as possible. Something becomes public only when it belongs to the object's contract and the alternatives were considered. Getters and setters are avoided where possible.

How we measure it
  • Do methods and fields have appropriate access levels?
  • Does the public interface make sense as a contract?
  • Can getters and setters be avoided?

Key Concepts of Domain-Driven Design (DDD)

Domain-Driven Design gives principles for complex systems centred on what the business needs: domain modelling, aggregates, repositories, and business logic kept inside the domain entities.

Key Concepts of Domain-Driven Design (DDD) · 1 of 6

General

In concrete terms

Domain-Driven Design concepts guide the architecture and the structure of the code. Developers and the business share one Ubiquitous Language. It is refined continuously, and names are chosen with care.

How we measure it
  • Are DDD concepts visible in the code?
  • Do team members understand DDD at a basic level?
  • Do developers and the business agree on the Ubiquitous Language?
Key Concepts of Domain-Driven Design (DDD) · 2 of 6

Domain Modeling

In concrete terms

The domain model represents the business problem accurately and is kept current as the domain evolves. Entities and their relationships mirror how the domain experts see the business.

How we measure it
  • Is the model accurate against the business problem?
  • Can every business scenario be expressed in it?
  • Does the model stay flexible?
Key Concepts of Domain-Driven Design (DDD) · 3 of 6

Complexity Managed

In concrete terms

Technical complexity is not added to business logic. The logic lives inside the domain (entities, value objects, domain events, domain services), apart from communication, security, persistence and similar concerns.

How we measure it
  • Does the business logic live in the domain?
  • Do the other concerns sit outside it?
  • Is the domain independent of how persistence and communication are implemented?
Key Concepts of Domain-Driven Design (DDD) · 4 of 6

Repositories

In concrete terms

A repository is a domain concept: it represents a collection of objects, independent of how they are stored. It should make sense to business people, and a technical implementation backs it.

How we measure it
  • Is the domain logic free of persistence details?
  • Do repositories stay simple from the domain's point of view?
Key Concepts of Domain-Driven Design (DDD) · 5 of 6

Domain Entities & Value Objects

In concrete terms

Domain entities are the main holders of business logic. They are not to be confused with JPA entities, which are plain data carriers. Immutable value objects are used where relevant, and not every concept has to be an entity.

How we measure it
  • Do domain entities hold behaviour?
  • Is state separated from behaviour (JPA entities versus domain entities)?
Key Concepts of Domain-Driven Design (DDD) · 6 of 6

Aggregates & Domain Events

In concrete terms

An aggregate groups entities inside one transaction boundary. Work inside an aggregate runs in one transaction; work across aggregates runs in separate ones. Aggregates talk to each other through domain events, with eventual consistency.

How we measure it
  • Are aggregates used correctly?
  • Is access only through the aggregate's public interface?
  • Is work across aggregates done through domain events, not one spanning transaction?
  • Are aggregates reasonably sized?

Principles of Clean Code and Architecture

Clean, maintainable code, object-oriented best practice and the SOLID principles. The aim: readable code, separated concerns and a rich domain model.

Principles of Clean Code and Architecture · 1 of 10

Expressive Code

In concrete terms

Code should read like a newspaper: headline, summary, then the details. We optimise for the reader. The code explains and documents itself, with carefully chosen names.

How we measure it
  • Does the code express intent, not only mechanism?
  • Can an outsider follow it at a high level?
  • How good are the names?
Principles of Clean Code and Architecture · 2 of 10

SOLID: SRP

In concrete terms

Each unit of code has one reason to change. No piece of code should serve more than one owner of business logic.

How we measure it
  • How large are the methods?
  • Are the needs of different business owners mixed in one unit?
  • Are business and technical reasons for change kept apart?
Principles of Clean Code and Architecture · 3 of 10

SOLID: OCP

In concrete terms

New behaviour is added mostly through new components, without changing the code that already exists.

How we measure it
  • Polymorphism, or chained conditionals?
  • How easily can behaviour be extended?
  • How decoupled are the behaviours from each other?
Principles of Clean Code and Architecture · 4 of 10

SOLID: Liskov Substitution

In concrete terms

A subclass must be a full substitute for its base class in every scenario. If it is not, inheritance is the wrong tool.

How we measure it
  • Does the subclass handle properly every message sent to the base class?
  • Can the subclass replace the base class everywhere?
Principles of Clean Code and Architecture · 5 of 10

SOLID: Interface Segregation

In concrete terms

Clients depend only on what they need. Interfaces are split so that each client sees only the methods relevant to it.

How we measure it
  • Do classes depend on methods that are irrelevant to them?
  • Can interfaces be split into cohesive sub-interfaces?
Principles of Clean Code and Architecture · 6 of 10

SOLID: Dependency Inversion

In concrete terms

High-level and low-level modules both depend on abstractions. Abstractions do not depend on details; details depend on abstractions.

How we measure it
  • Does the dependency flow run against the control flow?
  • Are the abstractions well defined and owned by the high-level modules?
Principles of Clean Code and Architecture · 7 of 10

Clean Architecture: Low coupling, High cohesion

In concrete terms

Closely related concepts belong together and unrelated ones stay apart. Components have the right size.

How we measure it
  • Are distant concepts decoupled?
  • Are related concepts cohesive?
  • Are components the right size?
  • Are interfaces used, and placed, well?
Principles of Clean Code and Architecture · 8 of 10

Clean Architecture: Clean APIs

In concrete terms

APIs follow REST best practice: resources are modelled well, HTTP verbs are used correctly and response codes fit the outcome. We take care over URIs, verbs, bodies and responses.

How we measure it
  • Does the API conform to REST?
  • Are resources and verbs correct?
  • Do the response codes fit?
  • Do the bodies allow future extension?
Principles of Clean Code and Architecture · 9 of 10

Clean Architecture: Good Separation of Concerns & Non-anemic Domain Model

In concrete terms

Application concerns are spread across layers and services. Domain objects are rich in behaviour and hold the business logic.

How we measure it
  • Is the domain model rich, or are entities mostly data holders with the logic in heavy, procedural application services?
Principles of Clean Code and Architecture · 10 of 10

Design Patterns

In concrete terms

Design patterns are used where they fit the purpose: a pattern is a tool, not a goal.

How we measure it
  • Is a pattern missing where it would help?
  • Is a pattern used for its own sake, with no real benefit?

Collaborative and Improvement Practices

Practices that build collaboration, learning and continuous improvement: code review, pair programming, TDD, experimentation, team autonomy and Continuous Delivery.

Collaborative and Improvement Practices · 2 of 7

Code Review

In concrete terms

Code review is for learning and feedback, not only for control.

How we measure it
  • Is there a review on every merge to master?
  • Is it peer review across the whole team, not hierarchical?
  • Are review comments labelled by severity (nitpick, thought, suggestion and so on)?
Collaborative and Improvement Practices · 3 of 7

Pair Programming

In concrete terms

Two or more programmers share one workstation and work on the same problem at different levels, the detail and the big picture, exchanging a lot of information and experience.

How we measure it
  • Is pairing allowed and encouraged?
  • Do people feel free to ask for help or to pair up?
Related principles
Collaborative and Improvement Practices · 5 of 7

Continuous Improvement & Experimenting

In concrete terms

The team looks regularly for ways to improve how it works and collaborates, and runs experiments based on that reflection. Experiments that bring no improvement are dropped; the feedback is built on.

How we measure it
  • Is experimenting encouraged?
  • How does management see mistakes and failed experiments?
Collaborative and Improvement Practices · 6 of 7

Continuous Delivery

In concrete terms

The software is always releasable. The deployment pipeline checks that it can be delivered and gives feedback.

How we measure it
  • Is passing the pipeline enough to release, or are manual steps needed?
  • How far is deployment automated?
Collaborative and Improvement Practices · 7 of 7

Test Driven Development

In concrete terms

Tests are written before any production code. TDD is mainly a feedback tool: it tells us about the quality of the design.

How we measure it
  • Do the tests cover all use cases?
  • Is the code easy to test?
  • Can it be tested in isolation, without heavy mocking?
Reading list
27 principles in 4 groupsIllustrative diagrams
02The complete list

All 27 principles. Four groups, one page.

Nothing hidden behind a tab. Press any principle to open it in the explorer above.

04

Collaborative and Improvement Practices

7 principles

Practices that build collaboration, learning and continuous improvement: code review, pair programming, TDD, experimentation, team autonomy and Continuous Delivery.

  1. 21Continuous LearningKeep improving the craft: better than in previous years.
  2. 22Code ReviewReview is for learning and feedback, not only for control.
  3. 23Pair ProgrammingTwo or more programmers, one workstation, one problem.
  4. 24Team AutonomyThe team decides how to organise itself.
  5. 25Continuous Improvement & ExperimentingReflect, run experiments, keep what works.
  6. 26Continuous DeliveryThe software is always releasable.
  7. 27Test Driven DevelopmentTests are written before any production code.
03How we know

Measured, not promised.

“We write clean code” is easy to say. So every principle on this page comes with its own check questions: things a team can answer about a real codebase with yes, partly or not yet.

71check questions
27principles
4groups

Some answers come from the pipeline: full test feedback arrives in under 20 minutes from a commit. The rest come from people looking at the code together. Try it on the card: pick a principle and answer its checks.

Review card

The review card lets you pick a principle and answer its check questions. All 71 questions are listed with their principles in the explorer above.

Illustrative · nothing is stored

Have a platform in mind? Tell Scout.

Describe what you need in a few sentences. A person on our team reads it and replies.

Start a project