Why use Coding Standards?
Code development happens at a fast pace, requires a quick turn around on deliverables, and is dependent on roadmap milestones. While often overlooked, coding standards are important to creating readable and consistent code and will have a significant impact on software development.
This topic became a part of my personal signature on writing code, especially after working on a project in which I changed from not using standards to having to enforce them. That made me realize how important they are. The project seemed doomed from the start due to unnecessary unresolvable complexity, not abiding by any coding standard at all, and other issues in regard to both design and style best practices.
What are coding standards?
Coding standards are no more than an agreed-upon, defined, and shared set of procedures or rules that specify the style in which the code and methods should be written. The bold text serves to point out that sometimes the following happens: developers who hoard decisive power over the project development may try to impose their own beliefs and unmerited opinions on others. That is not adhering to coding standards. Standards are not personal opinions; they need to be agreed upon, explicitly defined, and made available to those who need to use and abide by them.
In summary, coding standards are rules for coherence, as the generic concept of a standard implies.
Why are coding standards important?
How do they impact development and the project overall?
Adhering to a set of rules to make code visually consistent is a major factor in guaranteeing software quality, as it makes code easy to read, analyze, and work through. It becomes easier to maintain and extend, most importantly by newcomers.
Why is it easier to maintain and extend?
- Anyone involved in the project can look at any part of the code, comprehend it, and change it regardless of when it was written during the project.
- It will also be better safeguarded against bugs.
- Standards lead to lower code complexity and more elegant design, which makes code safer to change and test.
A somewhat unwritten rule is that a function should fulfill one single purpose. That results in shorter functions that are easier to read and comprehend.
If you end up with a +1000 instruction long function, it is likely performing several actions in sequence and with dependencies. It will be hard to read, to understand its purpose and execution path, to change something in it without breaking something else, and to test. The code should be more modular. That poorly-written function is highly prone to:
- having their purpose misinterpreted,
- break something else after changing code,
- not being testable,
- the occurrence of bugs, and
- causing someone other than the original coder to waste tons of time trying to understand it.
Even if it is a smaller function, mixing responsibilities and presenting no uniformity in writing style may result in these previously mentioned setbacks.
Here you have a visual example of code that is sloppy, incomprehensible, unorganized, and completely unstructured (in PHP):
At first glance, the code is hard to read, and to understand what it does. There seems to be no separation of responsibilities: from logic to data retrieval, view output, and presentation. There seems to be no coherence in the writing style. It looks like it may have been written by several developers, all with different signature writing styles. Here are some other issues:
- There is no design pattern
- Inline PHP code inside the view is not the best approach for readability and reusability
- No comments anywhere to explain what more complex code does
- No newlines or any sort of visual separation between blocks of code with different responsibilities
- Some variables are named carelessly, their names are without meaning (thus their purpose is inconclusive), and have no convention adopted, from snake case to camel case
- No limit in character length for each line
- Inconsistency on the calls to the ‘echo’ construct
- PHP opening tags are inconsistent (some are short tags, some are long)
- Spacing on operators and curly brackets are inconsistent, with curly brackets either on the same line as the control structures or the following line
- Conditions are also inconsistent in their presentation: some have curly brackets while some do not
- Foreach loop arguments are unconventionally named
- Alternation between the usage of single quotes to double-quotes
Here is an example of code written in Laravel with PHP with the same purpose as the previous code, but far easier to read and following an MVC design pattern.
The MVC’s Controller: it controls the application flow, i.e., returns the response for a request and passes it to a view.
A class that fulfills database-layer operations for one entity (Product):
The view, simply responsible for presenting the data to the UI:
There would also be classes for representing the domain entities (such as Product and Discount in this case), translated from database language into objects in the programming language itself through ORM, utility class, or classes with auxiliary functions and logic, classes for validations, etc.
As you can see, despite the code being longer, it is separated into PHP classes by responsibility: business logic, entities, database querying, view presentation, etc. It is more structured (in accordance with MVC) and organized. It is duly commented where the code is not entirely clear and properly documented. It abides by spacing and indentation standards and has a coherent visual style.
What about the disadvantages of coding standards?
Are there drawbacks to enforcing standards?
Isn't it costly to ensure that coding standards are used during development?
It shouldn’t be. It may have a somewhat small toll at first when adapting to a new set of rules or when getting used to different guidelines, but the effort invested in automating those into your own coding habits should be minimal, even unworthy of consideration in project effort estimates. To further emphasize that it is cost-free, there are tools available that allow to write code following specific sets of coding standards automatically. These tools are available for most languages, and can integrate most IDEs. For example PHP-CS-Fixer is used to validate PHP code against PSR conventions, Checkstyle to validate Java against Sun’s conventions, and so on.
This prevents bad code from being pushed live or code reviewers from wasting time on easily avoidable, time-consuming tasks, such as pointing out a missing blank line somewhere in the code (and from experience, no one ever wants to be THAT guy who in reality is just trying to ensure that clean, readable code goes into the codebase).
If the code becomes easier to read in the short term and is properly documented and consistent, it will be quicker to review (and correct if needed) with less effort. That translates directly into cost reduction and, since adopting standards is one of the most efficient approaches to prevent paying back later with interest at a technical scale, it directly reduces software entropy as well.
My experience tells me that adopting standards should be a mandatory practice. So far I have never come across anyone arguing otherwise. However, I have come across projects being developed under a highly-defended theoretical belief in all those commandments as if they were etched in stone. But then in practice they were avoided like the plague, as if they were arduous to apply. The only explanation I have for it is that they prioritized the speed of deployment over clean and consistent code. Nothing justifies that.
How do I use standards?
At university, I was taught to code a certain way: procedurally and stylistically.
The first thing I was re-taught (or rather was imposed on me) when I started coding at a company was to code a different way under their mantra, “what you learn in university is wrong and doesn’t apply in real-life business." So I adopted those new standards and other best practices as my new truth. Then, at a new project, my new truth was again dethroned by new standards believed by them to be the utmost truth. And so on and on from project to project. Where are the standards across these examples? There doesn’t seem to be any.
There is controversy in the coding community as to how a lot of coding features should be written, so a standard set is similar with the concept of interest, but not necessarily universal. Some things are somewhat agreed, while others are not.
But for those language features for which there is no consensus, what matters is that it is consistent within the project. This means it does not matter if you write:
as long as you stick to one of those across the project, and everyone else does the same. I've seen countless arguments defending one way or the other.
Some other rules, for instance, should keep true for every project, such as the +1000 instruction long function example; doing that is by definition a bad practice, regardless of the project or the language it’s programmed in.
How can you enforce this on a project to ensure it does not derail the conventions and escalate complexity, and reduce maintainability?
You can always use, in your local development environment, tools that validate adhesion to your conventions simply by running a command:
- decide on a set of conventions your code will abide by,
- configure whatever tool you’re using to comply with that set (adapt as you please as most are configurable or manually overridable), and
- configure it to run automatically on a Continuous Integration environment, so that if something fails to comply, the CI build generation fails, the developer is informed of it and can fix it, thus preventing bad, poorly written, or merely unstandardized code to be pushed live.
I’ve always used PHP-CS-Fixer for PHP, but there are others and other programming languages will have their own. The more you adopt this best practice as an automated habit of your own coding style, the more likely you are to write better code on the first run, and less likely to spend time fixing stylistic approaches in the end before pushing code.
Standards in place
What are some specific things that can usually be considered standards for achieving better-written code?
The first thing you need to understand is the purpose of each rule and why it is used that way.
The example I’ve referred to on curly brackets positioning (a controversial one) has my defense under the following explanation.
Most IDEs show a vertical ruler tracing matching opening and ending of code blocks, so:
- aligning those makes it easier for deeply nested blocks of code to be read;
- never exchange clarity for brevity by omitting curly brackets even if the language allows you to;
- if you click the closing curly bracket on this IDE (and others), it highlights the opening one and whether they’ll be visually aligned, so it is more straightforward to visually isolate and read blocks of code.
Here, it seems difficult to pinpoint where opening curly brackets are, based on the matching closing curly brackets (and vice-versa):
To me, this way makes it more visually appealing and readable:
Another example, which assuredly leaves no room for debate as there is no backing up the bad practice, is the character limit per line (80 is usually a somewhat good value to establish as a limit).
This looks bad. As you can see, the line extends way beyond a visual guideline that serves as a ruler:
Maybe reducing its length by splitting it into lines would make it more readable:
It looks better (for vertical code scrolling), but to me, it is still pretty much unreadable. This isn’t necessarily a line length issue now, but rather a matter of sequential comprehension of the criteria for this if condition. Maybe it is best to adopt a more readable, logical structure as the guideline:
This makes it much easier to point out exactly under what criteria that condition verifies.
Another example is that test classes should always start with the name of the function they test, then, in camel-case, have “Test” added to their ends: the class EmailController should be tested by the EmailControllerTest class.
In the end, the most critical action you ought to take is to automate the process of verifying these standards. The tools you use for this should check for both style and design problems.
Regardless of the style with which you write your code, the main point is that you should focus on coherence, making sure you follow a set of guidelines that is agreed upon (such as establishing a limit of characters per line or of instructions per function, comment the code that is not so directly comprehensible, etc.), and document it, and ensure to automate the code validation into CI processes. Style is not universally standardised nor a universal truth and what works best for some may not work for others, but adhering to standards in the project is paramount for readability, maintainability, and testability. In the end, the project that you and your team are working on should look like it was coded by one single developer alone.
About the Author
Rui Silva, PHP Developer
“Even though I’m enthusiastic about PHP and technology is my area of expertise, my background ranges from coder to designer, illustrator, and even photographer.
I have a logic-driven view of reality from the scientific half of my mind, but I’m heavily influenced creatively through the artistic half. ‘Madness is the playground of the creative’ is my inspirational drive”
– – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – –