Most software development teams will have a software development standards document of some kind, but the use and usefullness of them can vary greatly. I feel that often this document ends up as a token effort that has a minor impact on day-to-day work. When maintained and used properly I believe that software development standards play a key part in creating good software teams. Having the right content in the document and using it in the right way can make the difference between a file that never gets opened and a living document that is at the heart of a cohesive and efficient team and codebase.

Content

The content of a software development standards document is, obviously, what makes it worthwhile. I feel that software teams often have a limited scope on what they put into their standards; many (most?) are comprised of primarily syntax standards such as case and naming conventions, indentation rules, etc. I believe this is the least valuable content that should go into a standards document and that much greater value comes from broader content. Beyond syntax, key topics that I believe should be in every software standards document are: Software Patterns and Structures, and Software Design Principles.
The value of defining syntax standards for a codebase is primarly about consistency, rather than correctness. While there are some cases where it could be argued that a specific syntax is more functionally efficient than others, generally a developer’s preference is personal. But having a consistent style across the entire codebase generally makes readability, comprehension and discoverability easier for developers.

Syntax

When defining syntax standards I highly recommend using an existing standard, making specific exceptions only if there is a strong reason that is widely desired by the team. Using established standards means that new developers are most likely already familiar with them, IDEs and tools will usually have them out-of-the-box and, perhaps most importantly, it prevents arguments or discontent among developers who have clashing personal preferences.

Examples of the widely-used, existing standards are Microsoft’s C# Coding Conventions and the PEP8 Style Guide for Python.

The most consistent and efficient way to enforce syntax standards is to use a code style tool such as StyleCop or FXCop which identify violations of syntax standards and can even be set up to fail builds that don’t meet them.

Patterns and Structures

In most cases, syntax standards will be updated rarely once settled on (especially if delegated to an external standard). The most active and useful content in a standards document should be details of the software patterns, structures and libraries that the team uses.

Any significant, established pattern or architectural decisions that a team has implemented should be detailed in the standards document. The structure and reasoning should be explained (preferably with examples) along with the situations in which the pattern should be used.

Examples of implementation patterns that most teams should document include: unit and integration testing, dependency injection, APIs, data layer, etc.

This section should not be an exhaustive list of every occurrence of specific patterns in the codebase but essentially a toolkit for developers. If a similar problem or piece of functionality has been solved before then a developer should be able to look it up in the standards document and have a clear pattern for implementation laid out for them. Likewise, if a developer implements a solution or function that could conceivably come up again, they have to document it.

Too often in larger software teams you get a lot of wasted effort from developers reinventing wheels; maintaining patterns and structures in software standards helps to combat this.

Principles and Values

Something I haven’t seen done often but that I think can bring a lot of value to a team is to document overarching principles of design and decision-making. Putting this in writing provides developer discussions and decisions clear anchor points to hang on, guiding principles that most decisions should be able to refer back to.

The SOLID design principles are a good example for a team to aspire to, but even more general concepts can provide valuable guidelines. A principles statement as simple as “abstraction, encapsulation, decoupling” can give developers key points to refer back to in design discussions. And software design principles are just one aspect of a team’s day-to-day work. An example of a non-technical principle would be “make decisions based on business value”.

When a discussion or decision is bogging down in competing opinions, documented principles and values should enable people to identify how the various opinions aligns with those principles and weigh their value against them.

Usage

Software standards documents exist in some form in most development teams but in many cases they are stale documents, seldom updated and seldom read. To be worthwhile the document should be at the heart of the team’s development lifecycle, actively referenced in development, code reviews, design decisions and actively updated as the team and its software evolves.

Adding to and updating the standards should only be permitted after consultation and approval from key members of the team. Standards that are expected to be applied by the whole team should have input from a suitable range of opinions.

Managing teams of software developers can sometimes feel like herding cats; devs tend to have strong opinions and there is often no strictly “correct” answer to every problem. Creating and maintaining strong software standards can provide cohesion and foster a collaborative and efficient software team.