“Best Practices” as an anti-pattern

A Short Story of How Best Practices come to be

Imagine a beautiful green field, full of untapped potential, things to do, systems to build and happy customers to serve. You work alone, maybe with a team, slow or fast but you build a system, an application, maybe it is a website. Along the way you accumulate “dos” and “don’ts”. Perhaps you write it down, share it with the new folks who are joining no longer green but browning field. You are wise and some people call you “senior” or even “staff” something. You write down your ideas and call it Best Practices by Staff or Senior Somebody. That feels nice, you bestowed your hard earned knowledge to the next person, helping and guiding them for months/years to come.

Let’s unpack this a little bit. Okay maybe you did not actually wrote the Best Practices by Staff or Senior Somebody but you were recommended to read it or it was passed down as onboarding document or it came about some other way. In its origin these are a set of rules and ideas written at some point in people’s careers at a particular time in project’s lifecycle. They had some real or perceived value, and got shared across blogs, Twitter threads and internal Slack rooms.

So what is the problem?
The problem is that people take some ideas codified by some team that applied at some point in time to a specific project they were working on. It is very unclear if those suggestions will work out for you and your team. You need to know the context with which those trade-offs were made and what alternatives were considered. You will not know that information, but people will push to make dogmatic choices because they perceive it being a best practice.

DRY

The prime example of best practice that gets too much attention is Don’t Repeat Yourself. Coined by Andy Hunt and Dave Thomas in their seminal programmers bible The Pragmatic Programmer. If you read the linked chapter fully it actually makes a lot of sense. Most people stop reading at what authors call “a tiny and fairly trivial part” - don’t copy-paste lines of code. Duplication is considered a bad way of writing code but they stress that duplication of knowledge and intent is much worse than any other types of duplication. Code duplication is a symptom that rears its ugly head but it is certainly not the only one. If you are changing a single thing but have to make changes in multiple places - that’s bad.

The problem is that people since 1999 (and probably earlier) have been telling other developers to adopt “clean code” practices and “DRY it up”. Without the nuanced context of WHY and HOW this should be done, I find such comments to be about the most useless and lazy dogma out there. By taking this advice to the extreme logical conclusion, code base becomes a completely messy function soup where logic is stretched out into dozens of small files with tiny functions peppered across all of it. Typical day debugging such code involves searching globally for tokens and jumping from definition to implementation in your IDE until it gets dizzy.

What is the problem?

The problem is that people take some ideas codified by some team that applied at some point in time to a specific project they were working on. It is very unclear if those suggestions will work out for you and your team. You need to know the context with which those trade-offs were made and what alternatives were considered. You will not know that information, but people will push to make dogmatic choices because they perceive it being a best practice.

What do we do?

The has been good articles written about revisiting “clean code” and stop recommending it. I’d agree with all of those points raised and add that we should discover our own approaches and, instead of enshrining them into some immutable document, create a culture around mutability when it comes to “best practices”.

• let’s encourage new folks to the codebase to be asking questions of why it has been done this way.
• let’s rename “best practices” to “a set of ideas we have about the way we communicate in code based on current context” (maybe find a more catchy name).
• let’s not be afraid to revisit and change those set of ideas as they should change with the changes to requirements, team size, team seniority levels and tech stack.