Development Standards Lead to Predictable Software Development

Standards lead to consistency and consistency is good for predictability. Therefore, agreeing on standards is a useful way to achieve predictable behavior and products (the software). The most important advantages for maintenance are:

• It lowers the effort to understand how other developers have made decisions about design and implementation.

• It makes it more likely that code and tests can be reused by others. Not by copying and pasting, of course!

Development Standards Help Enforce Best Practices

Standards should reflect best practices. With the exclusion of externally set standards (e.g., legal requirements), standards appear when a user community apparently prefers to do things a certain way. Therefore, standards reflect what commonly works well in practice.

Thus indirectly, standards help to enforce development best practices. For example, with consistent naming conventions, the relationships between different pieces of code (be it methods, classes, components) are clear. This helps dividing code into the right abstractions and allows, for example, for proper code encapsulation.¹

A naming convention is a common type of standard. Identifiers that are very long or hard to understand are confusing for other developers, such as (a real example) AddPaymentOrderToPayOrderPaymentGroupTaskHelper. If those identifiers are named in a consistent manner, it serves as a system’s documentation of itself, because they show how functionality is organized technically.

This consistency is important. Standards are only effective when they are applied consistently. And tooling can help you with that (by facilitating or enforcing). A common example is to have a CI server automatically check code commits for certain characteristics (such as an issue identifier) and based on the result, allow or deny the commit.

Development Standards Simplify Both the Development Process and Code

Standardization decreases the number of specific decisions that developers need to make. Variations in implementations complicate maintenance, such as using different technologies to solve a similar problem. Using a single technology per domain ensures that developers can understand each other’s code, and learn from each other. This improves code reusability.

For large software development efforts it is common to have separate development teams working rather isolated from each other. Without standards, different teams may use a different development process and implement “custom solutions” that cannot be reused or they may duplicate functionality already present elsewhere.

Development Standards Decrease Discussion Overhead

Using standards limits discussion in development teams to the exceptions outside the standard. This is because with good standards, their context and application are understood. This eases understanding and communicating what is going on in source code. This also means that code is easier to transfer to new developers or other development teams.

Standardize Tooling and Technologies—and Document It

Standardization of tooling and technologies should include a summary description of their context. Context information should list a few simple situations with their solution. That leaves less room for developers to misunderstand in which situation (and how) they should use which technology.

Agreeing on standards verbally may not be enough to have a lasting effect. Therefore, centralize documentation of these standards (e.g., in a wiki or document). This allows for access from different teams that may be physically separated.

A clear standard for tooling and technologies includes the following:

• Prescribing a simple technology stack—for example, agreeing to use only one back-end programming language for implementing business logic.

• Scoping of technologies and frameworks—for example, using multiple specialized tools instead of using all features of one framework whose features might not be mature yet. Typically, areas such as testing, security, and performance warrant specialized tooling. This tends to require some deliberation, especially given cost trade-offs (licensing/open source). See Chapter 10 for elaboration.

• Default configurations of technologies or tooling (e.g., IDE, test suite, plug-ins). To achieve consistency, it is beneficial if default technologies and configurations are pushed over the internal network.

Chapter 11 elaborates on documentation efforts.

Considerations for Combinations of Technologies

Standards should be applicable and suitable to your organization and development team. The following are typical considerations for choosing combinations of programming languages and frameworks:

Assimilation

Is it likely that one of the technologies will evolve quickly with advanced capabilities? Such that it integrates (assimilates) qualities from the other technology?

Compatibility

How compatible are the different technologies? Do they require custom code to work together?

Time frame

Are the technology’s benefits really needed right now, or are you anticipating future demands?

Maturity

How long has the technology been around? How viable is usage of the technology?

Independence

Can different technologies be maintained independently or are they dependent on each other?

Specialized skills

Do the different technologies require essentially different technical skills? Is it likely that one developer can work with the complete stack or is specific training needed (or even different staff)?

Testability

Will the usage of different technologies significantly complicate testing?

Nonfunctionals

Are there foreseeable effects on non-functionals, such as performance or security, when using multiple technologies? This is likely to be the case when you foresee that testability is negatively influenced when using certain combinations.

Defining Process Standards

Process standards describe the steps that should be followed during the development process. Think of standards such as:

• “Every commit should include an issue identifier.”

• “Code should have a sufficient unit test coverage before it is committed.”

• “Every implemented feature should be peer reviewed on code quality by a senior developer.”

These examples could be enforced with pre-commit hooks that perform a check on the code commit before pushing it to the CI server. Peer review could be enforced by requiring authorization from a developer other than the one doing the commit. The aim of the peer review should be to check for adherence with standards, understandability, and general feel of code quality (is the code well tested, simple enough, isolated, etc?).

Though these are only a few examples, any of the best practices in this book can be standardized. When they are actions that developers must perform, you could also put them in your Definition of Done (see Chapter 3).

Coding Style

Most IDEs already have default style checking features that give warnings or even errors when your code formatting is not compliant with the predefined style configuration in the IDE. It is a good idea to use such a style checker, if only to be consistent in your code formatting. Do make sure that your style guidelines are not being suppressed. You would rather have an overview of violations than assuming that all code is according to standards. Commonly we see CHECKSTYLE tags such as the following:

// CHECKSTYLE:OFF
piece of code that violates coding style standards
// CHECKSTYLE:ON

Here, the style checker is bypassed by enclosing the violating code in between suppressing tags. This is something you should definitely avoid! There are several ways to facilitate this technically. For instance, pre-commit hooks can be configured to check for these tags or to ignore suppress messages.

Another good way to standardize coding style is to adhere to conventions and defaults rather than specific configurations. So, instead of writing lengthy mapping tables to relate the objects in your data access layer to the corresponding database table, you assume the convention that an object like “Book” will be mapped to a “book” table by default. This principle is known as convention over configuration, because you typically adhere to the convention and only violate it when exceptions occur. In general that leads to less configuration and less code. Using the conventions of the technology you use also improves transferability of the software, for example when hiring new developers. Conventions can be understood by newcomers to the team even when they originate from a completely different environment. Tooling and technologies help you in adhering to conventions with default presets.

Code Quality Control

What makes high-quality code? With maintainability as a quality aspect, some basic measurements for quality are system size in lines of code, lines of code per unit, the amount of duplication, and complexity of decision paths within units.

There are numerous static code analysis tools available for determining and enforcing code quality. Most of them can measure a few simple metrics such as size, duplication, and complexity of code, but do require some level of configuration. Combined with an IDE that includes built-in style checks, developers will get quick feedback on their code, which speeds up code improvement. Usually, style checks are performed immediately while coding, and code quality control measurements are executed in the CI server. Quality control checks can also be checked before a release, but by adding preconditions on a build in the CI server, you can do quality checks automatically. You can even ensure that all code has passed quality control before it is built for integration testing. This is rather strict, but practice shows that this is the best way to obtain high-quality code because it cannot be ignored.

Objection: We Cannot Work Like This!

“Our code keeps violating our standards. We cannot work like this!”

We do not expect that standards are a perfect fit right away, or that they should forever be held on to. Developers should understand the reasoning behind and the need for standards and what they intend to achieve. Resistance to standards may invite developers to circumvent them in clever ways. Hiding or not knowing violations is a bigger problem than knowing where violations occur. This may mean going back to the goals of the standards and possibly loosening them. Be careful when doing so, because having certain standards may serve a particular purpose. For instance, the standards you introduce may be high, but they reflect a quality level you want to have in the future. Then you should be explicit about this fact and have the team agree that they do not have to do it right first, as long as they understand this is something the team should work toward.

Objection: Can You Standardize on Multiple Technologies?

“Can we standardize on multiple technologies, such as using two programming languages for frontend code?”

Try to stick with one technology stack that is consistent, ideally with a single programming language. Simplicity is an important determinant notably for maintainability and security. Complex relations between technologies require a lot of testing and are at risk of breaking. There may be good reasons to use multiple technologies, to benefit from the specialties and strengths of each technology. For common considerations, see “Considerations for Combinations of Technologies”.

Objection: Organization Unfit for Standardization

“Our organization/project is not fit for standardization. We cannot get it through.”

This is essentially a management issue. If formal standardization is not possible, an intermediate solution is to verbally agree on standards; for example, agreeing within your team to apply a standard within (part of) a system. If a “bad” standard applies consistently to a whole organization, it is generally better to adhere to it consistently than to ignore it with custom solutions. Deviating from an organization-wide standard tends to lead to problems in maintenance and failing interfaces, in addition to a lot of miscommunication and trouble with other departments.