My whole blog is really about best practices – Java and API Design best practices specifically. When I was recently asked to give a presentation to our engineering team on coding best practices, I thought I’d have plenty of content to cover!
However, the direction I was given was not to go in depth on specific best practices. Instead, I had 15 minutes to talk about the "why?" behind it all. Why are we talking about this? Why is it important? What is the value and impact? Here’s what I came up with.
Story Time
To start things off, I shared this story from the book Clean Code:
I know of one company that, in the late 80s, wrote a killer app. It was very popular, and lots of professionals bought and used it. But then the release cycles began to stretch. Bugs were not repaired from one release to the next. Load times grew and crashes increased. I remember the day I shut the product down in frustration and never used it again. The company went out of business a short time after that.
Two decades later I met one of the early employees of that company and asked him what had happened. The answer confirmed my fears. They had rushed the product to market and had made a huge mess in the code. As they added more and more features, the code got worse and worse until they simply could not manage it any longer. It was the bad code that brought the company down.
Wow! This stuff is not just hypothetical. I honestly contend that nothing less than the survival of the company is at stake. It sounds drastic, but true stories like this make you realize how important this stuff really is.
Importance of Best Practices
Breaking it down a bit more, let’s explore a few of the many reasons why we care about best practices.
Fewer Bugs
Well written code always leads to fewer bugs. Consider the principle of least astonishment as an example of a best practice. If you’re not familiar, the principal states that "every method should do the least surprising thing it could, given its name." Obviously, if a method doesn’t do what users think it will, bugs will result. Here you see this direct correlation between a best practice and bugs in your code!
Static analysis tools like Spotbugs, Checkstyle, and Error Prone are built around this philosophy. They scan your code to make sure you are adhering to as many best practices as possible, hoping to catch bugs early. Bugs get more expensive the further they make it, so I highly recommend using these tools to help root out bugs before they ever get checked in.
Performance
Lots of people get worked up about performance. Managers insist that engineers are always making performance-conscious decisions, and many engineers get stuck spending hours trying to come up with advanced optimizations.
The truth about performance is that good APIs lend themselves to fast implementations. If you strive to write good programs rather than fast ones, you’ll often achieve the performance you’re looking for without any additional effort. Refactoring code to use best practices will often improve performance as a by-product!
Maintainability
Martin Fowler said it best when he said:
Any fool can write code that a computer can understand. Good programmers write code that humans can understand.
Code that is written according to best practices will always be easier to maintain. You’ll be able to add new features or fix bugs more quickly. The maintenance phase of the SDLC is the longest, so if you’re lucky enough to get to work on a fresh new project, make sure you do it right!
Technical Debt
Whenever code is written poorly, your team incurs technical debt. This debt represents the time it would take to update or refactor the bad code to use best practices. I’m sure you can think of several examples of projects or code bases your team manages with technical debt, ones that you hope you never have to work on again …
Just like monetary debt, technical debt accumulates interest. If you leave major flaws in systems unaddressed over time, you’ll pay the cost in the increased effort it takes to make changes or add on to it. The lesson is clear – avoid the perils of technical debt by using best practices consistently, and look for opportunities to "pay off" technical debts in your team by updating legacy code.
Mindset + Attitude
Hopefully by now you’re convinced that this stuff matters. So where do you go from here?
There are many great books and blogs out there (like this one!) that cover the details of coding best practices, and I’d encourage you to check out as many of them as you can. But for me, the most important thing to do is to adopt a whole new mindset and attitude when it comes to best practices.
Defend the Code
We’ve all written code hastily and said, "I’ll go back and clean it up later." And we all also know LeBlanc’s law: later equals never. Part of this mindset adjustment has to be a commitment to writing quality code every time.
But what about the schedule? Or the changing requirements? Or my manager? Developers love to put the blame elsewhere for bad code, but the truth is that bad code is always the developer’s fault. Managers and marketers look to us for the information they need to make promises and commitments; and even when they don’t look to us, we should not be shy about telling them what we think. Project managers look to us to help work out the schedule. We are deeply complicit in the planning of projects and share a great deal of the responsibility for any failures; especially if those failures have to do with bad code!
Many developers, especially junior developers, are worried about pushing back on what their manager says for fear of being fired. Thankfully most managers want the truth, even when they don’t act like it. Most managers also want good code, even when they are obsessing about the schedule. They may defend the schedule and requirements with passion; but that’s their job. It’s your job to defend the code with equal passion.
To drive this point home, consider this analogy from Clean Code:
What if you were a doctor and had a patient who demanded that you stop all the silly hand-washing in preparation for surgery because it was taking too much time? Clearly the patient is the boss; and yet the doctor should absolutely refuse to comply. Why? Because the doctor knows more than the patient about the risks of disease and infection. It would be unprofessional (never mind criminal) for the doctor to comply with the patient. So too is it unprofessional for programmers to bend to the will of managers who don’t understand the risks of making messes.
Boy Scout Rule
The boy scout rule – "leave the campground cleaner than you found it" – also needs to be part of your mindset as a developer. Any time you go in to make a change or fix a bug and you notice something that could be cleaned up – do it! The cleanup doesn’t have to be something big, just something like changing a variable name for the better, breaking up a function that’s a little too large, etc. By adopting this mentality, you’ll end up with projects and code bases that actually improve over time instead of slowly rotting away. What a concept!
Conclusion
I hope this post has laid out the full picture for why coding best practices are important and why you should care. If your team doesn’t already have one, consider creating a coding standards document where you explicitly define your expectations when it comes to best practices. A document like this should cover guidelines for formatting, documentation, logging, unit tests/test coverage, comments, and IDE warnings.