How to Ensure That Your Code Reflects Domain Concepts
  July 29, 2019

Imagine that you're taking over a legacy web application. When looking at the database, you see tables with names like `items` and `categories`, and the code contains variables with names like `a` and `object`. Long and complex classes and functions make it hard to understand what's happening and even harder to update the application with new functionality.

These naming conventions and coding practices make it difficult to understand and maintain the codebase. Clean code uses naming conventions that reflect domain concepts, and more broadly, the application itself is modeled after the business domain. That way, everyone is on the same page and the application is much easier to maintain over time.

Let's take a look at how to write clean code that reflects domain concepts.

Plan Beforehand with BDD

Behavior-driven development, or BDD, is a development practice that's designed to ensure that every line of code addresses a specific business purpose. In addition to cutting down on misunderstandings between business and technical teams, this approach helps developers write code around domain concepts and provides built-in documentation for stakeholders.

Short and frequent discovery workshops where business and technical teams meet to gain a common understanding of how software should behave are the most important parts of the BDD process. During these meetings, they have conversations about concrete examples that illustrate business rules and acceptance criteria for a given user story.

There are several advantages to this approach:

  • Developers understand what they're supposed to build before they build it, which eliminates rework caused by misunderstood requirements.
     
  • Stakeholders have a better understanding of the size and complexity of the story based on the number of questions and examples in the discovery workshop.
     
  • Test engineers can focus their efforts on proactively preventing defects rather than reactively fixing them since they're involved early on in the process.
HIpTest scenarios example

HipTest enables business and technical teams to collaborate using a common web interface where they can write scenarios. These scenarios are translated by test engineers or developers into executable specifications that run in a traditional test suite. They also form the basis for living documentation that can be easily accessed anytime.

Sign up for a free trial of HipTest today and see how easy it is to get started with BDD workflows in your organization.

Write Easy-to-Read Code

Most developers are familiar with the idea of writing maintainable code by adhering to common software design principles, such as the SOLID principles of object-oriented design. While these techniques reduce code complexity, they don't necessarily make it easier for developers to relate what they're doing to the underlying business.

Clean code should read roughly like plain English. Variables, classes and functions should have self-explanatory names that make it easy to understand what the code does. For instance, `area = width * height` is much more expressive than `x = w * h` — even though they make the same calculation. It's much easier for everyone to know what's happening.

Beyond naming conventions, classes and functions should be concise and easy to find. The single responsibility principle (SRP) helps avoid unnecessary complexity, while a uniform directory structure makes it easy to find files. The convention over configuration principle seen in web frameworks like Ruby on Rails is a great example.

Finally, the database structure of an application should reflect domain concepts. Table, row and column names should reflect the data contained within them. It's equally important to ensure that object-relational mapping, or ORM, is set up in a way that makes it easy to understand the business meaning behind data fields in the application.

Domain-Driven Design

Domain-driven design, or DDD, takes clean code to the next level by ensuring that domain terminology is used throughout an application. In fact, the core principle of DDD is the idea of ubiquitous language. The objective is to build applications that mimic real-world business goals, while maximizing the maintainability and understandability of the software.

The three core principles of DDD are:

  • Capture the Domain: Business and technical teams meet to create a ubiquitous language of the domain and set the foundation for harmonious models throughout the application.
     
  • Embed the Terminology: Naming conventions throughout the application should be based on the domain, including classes, methods, commands and domain events.
     
  • Protect Domain Knowledge: Domain knowledge should be protected from corruption from other domains, technical subdomains and other code to avoid blurring meaning.

Bounded contexts, or subsets of code that have an independent model with a specific interface for use by other parts of the code, are a core part of these components. All external knowledge and dependencies should be contained within the boundaries with only a well-defined set of commands that can be accepted externally to move messages around.

The process of identifying and classifying the relationship between different models and their bounded contexts is known as context mapping. This process helps mitigate and arrange dependencies between contexts to make the application as easy to maintain as possible when it comes to adding new features — which is accomplished by making small adjustments.

The Bottom Line

Clean code incorporates domain concepts to enhance readability and maintainability over the long-term. By improving communication between business and technical teams, you can avoid misunderstandings, ensure that everyone can easily understand the code and improve maintainability over time.

HipTest is a great way to keep everyone on the same page using a common web-based interface. Business and technical teams can collaborate on scenarios that can be easily converted into step definitions and incorporated into continuous integration to create living documentation. It's a development cycle that ensures everyone is always on the same page.
Sign up for HipTest to start using behavior-driven development to improve your development.