Programmers too often think of coding standards as something imposed by people with nothing better to do. Sometimes they give lip service to the idea but ignore the standards in practice. Neglecting them has real consequences when it comes time to maintain code. If it lives up to a set of standards, developers have a decent chance of understanding it and seeing how to fix problems. If it’s uncommented, poorly structured, and inconsistently named, figuring out what it does can be a nightmare.
The Benefits of Standards
Standards not only add consistency to code; they ensure that it provides adequate information about itself. We can see how this works in some common areas of standardization.
Comments let developers figure out what code was intended to do. They’re useful not just when handing off code to a new person, but when making sense of one’s own code from months ago. Programming languages and development environments often define a structure for comments, such as Javadoc. They come with software which extracts the comments and creates documentation. A person coming onto a project can see at a glance what classes and functions exist and what they do.
Naming standards help in telling classes, functions, and variables apart and in getting some information about them. Consistency in using initial caps, camel case, all caps, and underscores helps to distinguish functions from variables and global constants from local variables.
Usage standards limit variation when a language has multiple ways to do the same thing. Some languages have an excess of riches, and restricting the use of redundant features makes a body of code more consistent and easier to understand.
File organization and code structure help people to figure out where things are. With object-oriented languages, a common convention is to have one class per file and name the file after the class. Within the code, consistent layout patterns improve readability.
Function length should be capped, with exceptions allowed only for unusual reasons. The longer a function is, the harder it is to maintain.
In addition to making code easier to read and maintain, code that follows standards is more reliable. Some practices which are legal in a language, such as the “goto” in C, produce unreliable code. Developers should strictly avoid them. Consistent organization makes it evident what code is doing, so it’s easier to see when it’s doing something wrong.
Some violations of standards are actual coding mistakes. The programmer intended one thing but wrote another (e.g., “=” instead of “==”), producing code that looks legal but strange.
Why Coders Ignore Standards
If standards accomplish so much good, why is there so much code which ignores them? The reasons aren’t surprising, but they’re worth enumerating.
Insufficient information can prevent consistent code. If programmers aren’t sure what the standards are, or if they have to look in six different places to find all the information, they’ll find it easier to guess what’s wanted or just code however they like.
Haste and time pressure get in the way of clean code. When it’s 11 PM and they’re hoping to get out by midnight, programmers are going to be more concerned with whether the code works than with whether it looks clean. It’s called “technical debt,” and it often grows into a huge deficit. Functions turn into multi-page treatises. It’s easier to add a couple of lines of code than to refactor them.
Competing standards can confuse the situation. Some programmers on a team may come from a background where a different standard is used. It could be just as good a standard, but mixing the two is confusing. People who usually code in one language and are picking up another one are especially prone to applying the wrong standard.
Unrealistically complicated standards are apt to be ignored. There was once a fad for short function names whose names described their arguments in a compact, cryptic way. It didn’t last long. If a standard is too convoluted to follow, people will follow it haphazardly at best.
Organizational Ways of Improving Compliance
A coding team that wants to improve compliance with standards should take a two-part approach. It should adopt organizational practices that encourage following the standards. In addition, it should use software tools that check if code complies with the standards.
Code reviews are helpful, if they have the right focus. They aren’t just for shaming people into compliance. Reviews help developers to understand the standards and to recognize their role in making the code comprehensible. Questions like “What is this supposed to do?” will point out a need for comments or show where it’s hard to follow the code. If reviews turn into nitpicking sessions on indenting, they miss the point.
Allowing time is necessary if managers care about compliant code. If the pressure is always to produce code as quickly as possible, then it will be not only non-standard but buggy.
Technical Ways of Improving Compliance
Using software tools to validate code has proven a great help in maintaining code quality. That includes not only static analysis and unit tests, but tools for validating compliance with standards.
Static-analysis tools often include an option for checking code against standards, with a choice among multiple standards. Usually you can enable or disable individual rules to match your team’s practices.
These tools work best when they’re part of an automated development cycle. The validation tools won’t allow a release until all issues are addressed, so technical debt doesn’t accumulate. Developers will add missing comments and refactor code, just as they address failed unit tests.
Having everyone use the same code editor with the same configuration settings helps. If one person is creating indents with tabs and another with spaces, the result will be a mess. Using consistent settings helps to make the code follow standards as it’s being typed in.
Software tools do have their limits, and they aren’t a substitute for a commitment to good code. A validation tool can’t tell whether comments contain useful information or are just filler. Their biggest value is that they don’t let developers fall behind in cleaning up what they write. What really matters is that the developers habitually follow good coding practices rather than making them an afterthought.
