Stop Saying Best Practice

I'll give you the TL;DR right here:

Stop saying best practice and say what you're practicing

If you’ve never heard someone tell you about a best practice for whatever job role you're doing..I don't believe you. A “best practice” to people who build software is like a cold plunge to a VC, or CrossFit to a fitness bro, or the recipe that tastes just like the real thing to someone who is gluten free.

They can't help talking about how wonderful it is.

And before you start getting fired up, I’m not about to talk about why best practices are bad. I use them all the time. I learn them. I study them. I pay attention when new ones are shared around the community.

What I am going to write about is why calling them “best practices” is terrible.

I could wax poetic, but I can summarize this in a statement and a question.

The name best practice tells someone absolutely nothing about what they are practicing. If someone showed you some code and told you “this is the best practice” what are you going to say next? Why do we do it this way?

Naming matters (queue the meme about the two hardest problems in software).

No matter what name we might use there will probably be an explanation still needed to deeply understand anything, but I am going to give four new names you could start using to get 75% of the way there:

Community Pattern

Sometimes the reason you write code a certain way is because everyone else is doing it. This doesn't make it the “best” inherently. What makes this a “best practice” is because when everyone sees it they know exactly how and why it is there. This is very common in frameworks where the people in the community are already buying into a set of opinions on how to write software.

New contributors to your code can hop in and understand community patterns right away.

There is a great quote that captures this idea from a blog post written by Nicole Tietz

So, yes. As a principal engineer, I view it as my role to keep us off the bleeding edge as much as possible. That way, when we really do need to innovate, we have the capacity to do so. And when we don't need to, we can go really freaking fast.

Readability Pattern

A close relative of the Community Pattern, a pattern that is created for the sake of making more readable code is not always going to be the best at everything. It may feel more repetitive or take more lines, but the goal is not brevity. Sometimes the two align, shorter code may make it easier to reason about, but the only true goal is writing code that anyone can reason quickly about.

As a JavaScript dev one that comes up to the forefront of my mind is a teams choice to use for...of loops instead of reduce . People who REALLY love reduce will not agree (and believe me I am a huge fan of functional programming patterns), but not everyone can read a reducer one time a grok what is happening. Instead of adding that barrier your team may choose to lean towards for…of loops to make it a no brainer when trying to parse the output of the operation in question.

Performance Pattern

Ah performance patterns. Patterns of this nature often fly in the face of the previous two.

The code to squeeze maximum performance out of the system doesn't always give you the courtesy of being the easy way to write it, but when you need a pattern like this it is because the trade off is understood by the team and worth it. (Never shy away from heavy documentation on these patterns)

Guardrail Pattern

This is the last one I will throw in here. Some patterns exist to avoid known foot-guns. Things like this make their way into Community Patterns often times, but when these are given the name “best practice” it can be easy to confuse the real reason these exist.

A favorite of mine is “No Magic Numbers”. We have all done this before. If you're unfamiliar let me give a quick run down.

Magic Numbers are most often numbers used only once and so you justify in the moment that it would be a waste to put this in some variable.

Pfft we only need to multiply the total by 47.5% here I won't forget why…

…2 Years Later (SpongeBob narrator)…

…Hey! Does anybody know why this is multiplied by 47.5%? Oh that? Yeah Kevin wrote that like 2 years ago before he left. We don't know why so we just don't touch it…

So enter the guardrail pattern of assigning all of our numbers, even one off ones, to a variable.

Conclusion

In conclusion, stop saying something is a best practice. Classify your patterns for what they are best at doing, and tell me that.

Addendum

After having this shared around on Hacker News and social I wanted to make some extra points on top of my points above:

• When trying to optimize "distribution" of your information I get that more people are likely to search or dig into a "best" practice. That is valid, but if that is how you're hooking people in make sure you dig deeper than that once you have that attention

• "People are smart enough to understand best doesn't mean best..." That is a false assumption. You may experienced enough to make that deliberation based on just reading through what is shared, but not everyone is. It is our job to help those more junior or learning to better understand why something is recommended instead of just saying "Do this, but I expect you to know when you shouldn't".