Coding standards and development: A general overview

There are many positions held by different developers around coding standards.

On one side of the coin are those entirely opposed to enforced standards; developers are fluent in their own thought process, and requiring that they abide by specific rules is a resource cost that outweighs any benefit.

ut on the other side, the ethos is that no codebase ever belongs to just one developer and that coding standard is the bridge that allows one person to more efficiently pick up where someone else left off.

In this article, I’ll explore the thoughts behind code standards and give a scenario that will help illustrate some common places where coding standards are helpful and can cause friction. Where friction exists, I’ll discuss how to move forward through it.

What exactly are code standards?

Coding standards (or conventions) are a set of rules that must be followed when developing code to achieve better code structure quality, improve readability, and make maintaining the code easier. They are often based on formatting and vary in resolution from cross-category standards to organization, language, or platform-specific standards. Code standards typically cover file organization and naming conventions to indentation, white space, statements, declarations, comments, and more. While many standards are beneficial, many are also subjective and based on a preferential programming “style” that may or may not be shared by other developers. Let’s look at a contentious example or two:

Example 1: Always place a curly brace on a new line after a logic statement

This simple formatting standard is shown below in PHP but is a standard that applies across many other languages, too. It includes little technical value and more based on style and preference. Which do you prefer? Maybe this is a standard that conflicts with your own style and preference.

Standard enforced

If (x > 0) 
{ 
  y = 1; 
  x--; 
}

Standard not enforced

If (x > 0) { 
  y = 1; 
  x--;
}

Example 2: Every module directory in the project folder must have a readme file

This is an example of an organization-level coding standard. Enforcing this standard provides good value for the cost because it gives any new developer working with this module an overview of the purpose and any special information or pertinent examples.

Standard enforced

 

Standard not enforced

 

Should coding standards be enforced?

Enforcement of standards isn’t something that will be done on its own. It’s a decision made at the individual, communal and organizational levels. Often, standards like in the examples shown above are being used by individuals whether they are enforced or not. Sometimes they are enforced, but in an unofficial, undocumented way (making it look more like a preference instead of a standard). So, should coding standards always be enforced? This is the wrong question to ask. Instead, some better ways to phrase it are:

• To what degree are coding standards to be enforced?
• How are standards evaluated against one another?
• What documentation exists for coding standards and their value assessments?

In the real world, standards are important but maybe following all of the standards just isn’t time or cost-effective. Maybe there is very little uptake in the development community for the standards, so using them really doesn’t achieve much. Maybe the standards are unclear and conflicting. All of these factors could have an impact on whether or not standards should be enforced.

When standards are being followed at large, and there is good documentation, the effort needed to enforce standards is much less. See the Making Drupal Code Standards Work for You blog post for an idea on how a developer interacts with established coding standards in their day-to-day work. In that article, you’ll see that applying coding standards can become efficient with the help of modern-day Integrated Development Environments (IDEs) as much of the small, tedious stuff (like the first example above) can be found and fixed automatically.

A common code standard scenario

Patrick is a junior developer working with his team lead, Miranda. Miranda is a typical standards keener who wants to see clean, consistent code with a reliable format based on the most up-to-date coding standards. Patrick, being new to programming, hasn’t adopted any kind of discipline around coding standards in his workflow.

Miranda assigns Patrick to build a new feature and Patrick hits the ground running. He completes the feature in his own way and hands it off to Miranda for a code review. When Miranda begins her review, she immediately notices examples of coding standards not being followed. Before spending any more time on the review, she passes it back to Patrick, letting him know that he will need to implement the coding standards that were lacking. Patrick obliges and bounces the feature back to Miranda after implementing the code standards. Miranda now begins the actual code review in earnest.

Looking at the scenario above, at first glance it may appear as though coding standards got in the way of the actual code review process. Miranda had to spend time pre-reviewing code for standards instead of reviewing the code for the feature. We can see now that coding standards have a cost. It takes any developer some level of attention and discipline to write code according to a given set of standards, and on top of that, the standards have to be included in the review process. When code standards are being enforced, the standards are part of the review process and there are benefits.

One payoff for this cost lines up with Miranda’s goal of having consistently formatted code between developers, meaning it will be more efficient for new developers to pick up where somebody else had left off.

Another payoff is when it comes time to refactor the code. Refactoring is a common process of restructuring existing code without changing its external behaviour in order to improve the code and adopt new techniques and standards. During refactoring, coding standards will provide a more reliable foundation for making these refactors more efficient.

Something important to note here about the scenario above is that the degree to which these standards are enforced is based on Miranda.

Code standard ownership, responsibility and cost-benefits

In the scenario above, Miranda doesn’t own the code that Patrick produced, but she is responsible for the coding standards being implemented properly. Let’s expand on that example some more.

One of the standards that Miranda is ensuring is the “No magic number” principle. This principle sets a standard in programming that unique values with unexplained meaning or multiple occurrences should preferably be replaced with named constants. A request for change is made that requires refactoring one of the hardcoded number values that exists in the code. For the sake of specificity, let’s say in this example that there is some code functionality that gives an ecommerce customer a 2-hour window for them to be cancelled or changed. The request for change is to set this 2-hour window to 1 hour and Miranda needs to provide a time quote for completing the work.

Standard enforced

If the coding standard based on the principle of “No magic number” was strictly enforced, this change would be as simple as updating the value of a single constant (const ORDER_CLOSE_WINDOW = 2;) that exists in one place in code. Updating the number here would update anywhere in the code that the constant is used.

Standard not enforced

If this coding standard had not been properly enforced, then the refactor will become more complex as instances of this number being used will have to be individually found, changed and tested wherever they are in the code. This would be prone to error and potentially be difficult to fully test.

Because code standards had been enforced when this feature was first implemented, Miranda can quote one hour for this task. Had standards not been used, she might have quoted 3 hours or more. Here we can see the true cost-benefit of code standards in development — i.e. better coding standard = smaller estimate. With more complex scenarios, Miranda’s trust in her team having adhered to coding standards will act as a tool for making more confident decisions when she makes estimates.

Something worth noting regarding the cost vs. value of coding standards is that they are often trying to solve a problem that doesn’t exist yet. This makes it challenging to accurately measure the benefits of coding standards, while the cost is much more straightforward to measure, i.e. how much extra development time was used for XYZ standard to exist. This makes it a difficult case for a developer to argue when resources are being allocated.

Code standards are a process, not a goal

Implementing coding standards is not a finish line that you reach after you’ve won the race, it is a process that will evolve over time as standards are updated, teams shift, projects change, and people grow. The coding standards being the same in any two given projects is unlikely.

Miranda’s project is using a standard that has given them a proven advantage, but let’s now imagine that her scenario exists in a world where the “No magic numbers” principle has not caught on yet. By using a constant as a standard, Miranda’s project has something valuable that other developers could also use, but now the problems become:

• What metric can be used to determine if the “No magic numbers” principle is a viable standard for a given project?
• How are these advantages being communicated between teams in general?

Coding standards are a continuous conversation between the people who are responsible for making resourcing decisions and those doing the work. Miranda’s project might have benefited from a given standard, but another project might not. In this way, standards become and evolve. Sometimes a standard makes so much sense that it catches on and becomes widely accepted. Sometimes standards become deprecated and eventually removed when they are no longer useful. There is any number of circumstances that will be asking for time and attention with coding standards and what works well today might not work well tomorrow. As I said, it’s a process, not a goal.

Code standards have value, but beware of decision traps

When working with coding standards, remember that they are a secondary objective. They can easily become a pitfall for Parkinson’s Law of Triviality (a.k.a. bikeshedding) which “is an argument that members of an organization give disproportionate weight to trivial issues.” Are we building a nuclear power plant or a bike shed? It’s hard to build a nuclear power plant and easier to build a bike shed, which makes the bike shed an enticing point of discussion which distracts from the far more difficult and complex task of the power plant. Bikeshedding is often applied to software development in a similar way — it’s hard to solve the primary problems that are required for the project and easier to work on coding standards. If this fact isn’t a cornerstone of a coding standards discussion or debate, the risk of spending undue time on a given resolution increases. Let’s look at an example.

Example: toCamelCaseOrNotToCamelCase

Usually, violations that are more difficult to address are the ones that are more important. Let’s say a code review comes back with the message: “You didn’t use camel case here,” but didn’t point out that the class was not developed using solid principles. This message distracts and one of Miranda’s co-workers offers her a suggestion of a useful coding standard to follow. She disagrees and they debate this back and forth over a series of meetings. How long would they go back and forth like this until the benefit of time gained for implementing a given standard is outweighed by the cost of making the decision?

What I’m getting at here is that coding standards serve a purpose and have value, but the value of the project supersedes its coding standards. Sometimes, a decision will have to be made with less than ideal information and must be made quickly.

Continuing the example, Miranda makes the executive decision to cease discussing the coding standard in question with her co-worker and to not implement the standard. Miranda has an ace in her sleeve though, she creates a metric that captures when the coding standard would have become valuable and uses that as a logistical re-assess point. If the coding standard that she did not implement proves that it would have been useful, she commits that, given this new information, she will reopen the discussion around that standard. Some qualities she might consider for a standard to be re-assessed could be:

• Is the standard used widely or by reputable organizations?
• Is there tooling to make the standard automated, or nearly automated?

If the standard passes these metrics, they might just be worthwhile to implement after all.

Coding standards and better communication

I heard once that developers aren’t actually people as their existence cannot be proven. They are seen here and there on video calls, but that could easily be a hologram. In all seriousness though, egos come into play and people become invested in what they believe in. Not only that, but humans are social creatures; when another person tells us that we have erred, it hurts a bit even if we know that we’re on the same team.

Having coding standards that are strictly enforced by an automated tool or other means takes some of the sting out of this confrontation and avoids alienating people. If you can easily point to a mistake in code and provide a documented reason why it’s a mistake, this is a welcoming improvement in communication and helps overall team morale by taking out personal bias.

Communication is also improved because one developer can read another developer’s code more easily and build off of it. Standards help everyone get on the same page which is especially important when working with large codebases, frameworks and architectures. If the rule is: everyone stacks your honeycomb on the last honeycomb, but one person stacks a square, then it takes extra work to compensate for this. Not to mention, that square will always bee there, deeper and deeper in the source code until finally refactored out.

In conclusion

Coding standards are a discipline based on consistency. There is a strength that comes from stability, but decisions made in the past must be revisited periodically which leads to an ever-evolving process. Bikeshedding is one of the main pitfalls that developers are trying to avoid when coding standards are not prioritized, but adhering to some kind of standard is an important marker for consistent code being produced and great team communication.

Standards can exist at different levels: Organization-specific, language-specific, platform-specific, and variations that span across these categories. Asking whether standards should be enforced is the wrong question in my opinion; it’s better to ask how applicable a certain standard is to a given project and an estimate of what the cost of adhering to it would be. This allows a feedback mechanism so that resources can be re-allocated based on a metric, instead of a gut feeling.