Write More Dumb Code. There is definitely a balancing act in… | by David Van Fleet | Apr, 2022

There’s undoubtedly a balancing act in how intelligent or dumb you make your code

Picture by Elisa Ventur on Unsplash

What do you suppose is extra necessary? Being intelligent in writing your code? Or making it comprehensible to others? I’d completely want readable code over one thing that’s obscure for the sake of being “intelligent”!

The issue is, as builders typically we really feel a bizarre pleasure in writing one thing that others can’t perceive. We persuade ourselves that others can’t perceive it as a result of we’re “smarter” or “extra artistic” than they’re. I’d problem that pondering and argue that if we have been actually a artistic, sensible dev, anyone (particularly these junior to us), ought to be capable to see precisely what our code is doing at a single look.

So as a substitute of making an attempt to create one thing so “intelligent” that no person could make sense of it, let’s attempt to write one thing so “dumb” that even somebody with hardly any expertise can learn and perceive it with out a lot effort!

So how can we write dumb code? Listed here are some factors to think about.

Think about we’re engaged on an MLB statistics software. Our purpose is to create a react hook that can be utilized to fetch a baseball staff from our database by id. These examples will use react-query and axios.

Even if you happen to don’t have expertise with React or these particular libraries, it’s okay. Keep in mind, our purpose is to make this as readable as attainable, whatever the reader’s expertise stage. Let’s have a look at a couple of issues we will take note to ensure our code is readable to others on our staff.

Take into account Scope

Generally, contemplating the scope of the place you’re working could make an enormous distinction to readability. On this first instance, we put our question operate, question(), outdoors the scope of our hook, useTeam(). Doing this requires a reasonably in-depth understanding of how react-query works, particularly what arguments are handed to the question operate, and the way these arguments are structured. Right here’s the way it appears to be like…

Relying on the make-up of your staff, this hook could also be fairly complicated. Whereas it does present an intensive perceive of react-query on the a part of the dev who wrote it, it might be needlessly sophisticated (destructuring the arguments handed to question(), destructuring the queryKey array, utilizing a throwaway variable _, and so on). Does it actually should be written this manner? Would altering the scope of question enhance the readability? Let’s attempt it out.

Making this straightforward change eliminated a lot of the complication of the primary instance. For the reason that question() operate is now in scope of useTeam, we have now entry to the id with none of the sophisticated strategies used to seize it. That is already way more readable, and even a dev with no react-query expertise can simply perceive what’s occurring within the question() operate.

Take into account Variable Names

One other method to enhance readability is to make use of extra declarative variable names. Within the instance above we named or question operate question. Does that imply something to the reader? No! we don’t know if its a GET request, a POST request, what it’s requesting, what the response is, what the params are, or the rest!

Wouldn’t it’s simpler to know what’s occurring if we named that operate one thing extra declarative?

Now we will know what’s occurring within the getTeam() operate with out having to really learn the code within the operate. We are able to make an informed (and proper) guess that the operate makes a GET request for a single staff.

This makes it method simpler to know what’s occurring within the useQuery hook, the place we name the getTeam operate. Once more, even somebody who doesn’t have expertise with react-query can have a look at this and provides a reasonably good guess of what’s occurring, simply primarily based on the way it reads in English.

Add Feedback as a Final Resort

Ideally, we should always write code that’s so readable that feedback don’t add something of worth. If our code reads like a paragraph in English, why would we have to add something to it?

Nonetheless, relying on the complexity of what we’re doing, feedback could clarify the strategies that we’re utilizing or why we’re doing one thing a sure method.

For instance, take into account the next drawback: we have to write a operate that takes two arguments, an array of integers, and a goal sum.

Our operate must return a boolean that tells us if any two integers within the array may be added collectively to equal the goal sum. Have a look at the next code and see if the feedback add any worth…

It is a very laptop science-y operate. We’re constructing an algorithm that implements a selected method to resolve the issue we’re given. There aren’t actually some ways to make this very readable. We’ve already given consideration to how we’ve named variables.

We’ve pulled a number of the logic into its personal features so the algorithm reads extra like English. However even nonetheless, with out the feedback, any person may be fairly confused by what’s occurring on this (already fairly clear) operate. Including a couple of easy feedback makes it simpler for any person to determine the algorithm.

There’s undoubtedly a balancing act in how intelligent or dumb you make your code. The “intelligent” examples on this article could also be very readable for knowledgeable devs in your staff.

In case you suppose your staff members will discover the intelligent code readable, then by all means use it in case you have a cause for doing so. But when your staff has extra junior devs, or if you happen to’re utilizing libraries they aren’t aware of, be certain that to “dumb it down” a bit to ensure it’s readable.

It doesn’t matter what your staff make-up is, it’s best to by no means be happy with writing one thing that’s onerous for others to know. As an alternative, take pleasure in writing code that’s environment friendly and performant, however remains to be simple to learn and perceive by all people in your staff!

More Posts