I am not a researcher so I don’t have the statistics to back up my assertions for the post, but I have mostly written programs for a living for over 25 years — in my opinion — there is one hugely important aspect of coding standards rarely discussed and that is: reproducability.
“Reproducability” defined
What do I mean when I say “reproducability?” I mean your coding standards should be such that — if you are following them religiously and given the same set of requirements — you will write the exact same code today as you will write it in six (6) months, and as you did write two (2) years ago. Reproducability is consistency taken to the extreme, but in a good way.
But you ask “What about learning? Shouldn’t I be constantly improving my code?” And to that I answer, “Yes, of course! Reproducability is something to strive for in your coding standards, not something that you will or even should always achieve.”
A key coding standard metric
You should constantly be striving to improve your coding standards. But I am proposing that one of of the most important metrics should be the level of reproducability you can achieve given the current state of your coding standards.
“One of of the most important metrics should be the level of reproducability you can achieve given the current state of your coding standards.”
Me
Not just for you, but for your team
Unless you are a hobbyist or the rare programmer who can make a living never working with other developers and where no other developer ever has to work on your code then your coding standards should be team coding standards, not just personal coding standards.
“Your coding standards should be team coding standards, not just personal coding standards.”
Me
Don’t just take my word for it
But who am I? Just another programmer with an opinion? Yes, but don’t take my word on this alone, consider what others have to say about highly correlated topics.
- Consider one of the primary goals of Google’s GoLang team: “Go must work at scale … with large teams of programmers working on them.”
- And why the Google team added
go fmtas standard tooling (emphasis mine): “Gofmt’d code is easier to write, easier to read, easier to maintain, and uncontroversial“ - Or what CircleCI’s evangelist had to say: “When developing software with a team, it’s important to ensure code is formatted consistently between contributors.”
- Or what one of the authors of the widely used Go library Cobra had to say: “We’ve had decades of endless argument and debate about the correct format of software. … Golang has done away with these endless debates once and for all by shipping a formatter that ensures that all go code follows the exact same format.”
- Or what Andrew Gerrend from Google had to say about coding quality: “Readability is the defining quality of good code.”
- Or what the team as Stream had so say about enforced code formatting: “It’s important that formatting is consistent, but the actual formatting standard doesn’t really matter all that much. Gofmt avoids all of this discussion by having one official way to format your code.”
- Or lastly from the online book “Effective Go”: “People can adapt to different formatting styles but it’s better if they don’t have to, and less time is devoted to the topic if everyone adheres to the same style.”
Yes, the above is almost exclusively from the perspective of Go and almost exclusively about code formatting. But Go is a language designed in service to software engineering, and probably the most common aspects of coding standards is formatting.
The question then is, why not extend your coding standards well beyond formatting?
Your standards should prescribe patterns
More importantly than coding conventions, your team standards should prescribe as many common coding patterns as you can reasonable codify, enabling them to in-fact reproduce effectively the same code across different times and with different developers.
Note I am not referring to low-level Gang of four design patterns but instead higher-level coding patterns that are typically specific to the language(s), library(s), framework(s) and/or CMS(es) that you use to deliver your software solutions.
Standards shouldn’t need good judgment
The best coding patterns are ones you do not have to think about but instead that you just apply. The thinking should have been done when the patterns were developed, and then during coding you should just apply them.
Now you might argue that this makes programming uncreative, a rote task, and one that does not leverage the intelligence of the developer. But nothing could be further from the truth.
You can never codify everything into a code pattern or standard, so there will always be problems to solve. Standardizing the code patterns once and then reusing them allows more time to tackle the hard, interesting problems that energizes most developers, not the least of which is because said standardization can significantly reduce the number of bugs you need to track down.
Example code pattern(s) for your standards
I would have liked to have provided copious examples of higher-level coding patterns to help you visualize what I an discussing here. But doing so would mean postponing pressing the “Publish” button, probably indefinitely. So instead I will leave you with one for PHP, and then plan to add the coding-patterns tag on future blog posts so that — if you are reading this in the future — hopefully I will have blogged about many examples since publishing this post.
The Break/Continue Guard Clause pattern
This is an example of a PHP coding pattern I recommend from my prior post on avoiding early returns in your functions/methods. It refactors WordPress’ wp_setup_nav_menu_item() function using break with do {...} while (false) instead of early returns. And I will be writing about this pattern more in-depth in the future:
function wp_setup_nav_menu_item( $menu_item ) {
do {
if ( isset( $menu_item->taxonomy ) ) {
_wp_setup_taxonomy_nav_menu_item( $menu_item );
break;
}
if ( ! isset( $menu_item->post_type ) ) {
break;
}
if ( 'nav_menu_item' !== $menu_item->post_type ) {
_wp_setup_post_type_nav_menu_item( $menu_item );
break;
}
_wp_setup_nav_menu_item( $menu_item );
} while ( false );
return apply_filters( 'wp_setup_nav_menu_item', $menu_item );
}Summary
In closing I leave you with the core message of this post:
Strive for Reproducability in your Coding Standards
Me