Programming style debates are too often focused on unimportant formatting choices at the cost of vital style, naming, and coding conventions. Developers will argue more about tabs vs. spaces for indenting than when methods should be split up. Anyone who’s ever received a code review with feedback focused on whitespace and formatting knows how it obscures valuable feedback.
Organizations that don’t define their programming styles inherit them from the code itself. Engineers guess the accepted practices mixed with their own assumptions. As projects mature this variation in styles and conventions increases.
Every pull request submitted without defined coding standards increases code complexity. These differences can range from function length to naming conventions. These issues build on one another making the code more difficult to read and maintain.
Why does everyone talk so much about maintainability?
Tom Cargill of Bell Labs said, “The first 90% of the code accounts for the first 90% of the development time. The remaining 10% of the code accounts for the other 90% of the development time."
You probably already understand why Cargill jokes how programming the last 10% of your code takes as long as the first 90% (making the total time 180%). Code that’s hard to read and understand takes a lot of time to change. Far more than the time it took to add the original features.
As features are added, projects are bound to get more complex and challenging to maintain. Even with a focus on code quality, teams find complexity increases with every pull request and code review. Without defined standards, the same changes can make the code exponentially harder to understand and update.
“Indeed, the ratio of time spent reading versus writing is well over 10 to 1. We are constantly reading old code as part of the effort to write new code. …[Therefore,] making it easy to read makes it easier to write." — Robert C. Martin, Clean Code: A Handbook of Agile Software Craftsmanship
Maintainability is one of the top reasons most dev teams prioritize code quality. It’s usually even listed as part of the definition of clean code.
But here’s the catch: if you ask ten developers what clean code means inside their organization, you’ll get thirteen different explanations.
Some will describe code quality as readability, or functionality or testing, and others list style rules. Without a source of truth, they can all be right. How to prioritize coding standards and style is debatable. In practice, developers value different programming styles, so reaching alignment across your development team is important.
One might write verbose methods that they believe are easy to read. While another might focus on writing the same method in as few lines as possible. Both can make the argument that their code is higher quality compared to the other.
Different views aren’t the issue. What matters is how a team as a whole communicates towards achieving code quality.
This is why documenting your organization’s coding standards can have a major impact on the quality and maintainability of your code. Developers on your team who follow the same practices as the of the rest team write code that’s more consistent and readable. During code review, reviewers also will know what code quality issues are important to the team, instead of falling down a rabbit hole or nitpicking minor style issues.
What’s next?
Fortunately, there are a lot of resources and templates to get you started. In our next post, we examine ways to create and implement a programming style guide with your team.
