This content originally appeared on Level Up Coding - Medium and was authored by Jacob on Software
As followers of this blog may have noticed, I’ve been referencing Clean Code quite a bit the last several weeks. I started reading the book on the advice of a friend and fellow software engineer, who extolled the values of this classic programming text. I’ve been going through it very slowly, reading just one chapter a week to make sure I plant these lessons deep in my head. Still, I can see how Clean Code is having a significant effect on how I think about the code I write as well as the code I’ll write in the future.
Written by Bob Martin — or “Uncle Bob” to those who know of him — Clean Code was first released in 2009, and follows some of the best insights programmers have discovered over the last several decades. You’ve probably heard of it before, and it’s almost certainly on the shelves of nearly every company in the tech space. As computation is all about making machines that can do particular tasks more efficiently than humans, we would do well to listen to some of the most insightful minds of the trade.
For this blog post, I’m going to look back at code I wrote for a previous project, refactoring it to reflect on the lessons I’ve been learning from Clean Code. As I’ve only read the first couple of chapters, I’ll be very specific with my insights, focusing only on meaningful names and comments. I hope it inspires you to always, whatever you do, write clean code.
More specifically, I’ll be refactoring a simple quiz app I built to teach myself TypeScript. Feel free to check out the GitHub repo here or read my Medium article on learning TypeScript. Run the app locally and you should see something like this:
I had a lot of fun learning TypeScript, and I definitely understand why programmers would want all the functionality of JavaScript with stricter typing. While I loved building this small app, I suspect I might not have written the cleanest code possible. And although this was a solo project where I was the only developer, someone else could easily come along and decide to build on top of what I made. Collaboration is part of the beauty of the internet, and tools like GitHub are what make programming so powerful. However, If another programmer came along, my lack of clean code would undoubtedly slow them down. As Uncle Bob tells us time and time again, the amount of time reading code as opposed to writing code is easily 10:1. Let’s dive into the code and see what we can refactor.
Names
One of the first chapters of Clean Code is all about names. The first sentence in the chapter reads “Names are everywhere in software.” We’re constantly naming functions, variables, and arguments, among other things. Because naming elements of our programs occurs so often, we should do it well, giving designations that are clear and meaningful. Let’s take the following function:
The above function is fairly simple. It takes in the value of the click event (whichever answer the user picked) and checks to see if that answer is correct. While I’m fairly happy with some of the naming conventions I used here, I think we can do a bit better. Firstly, I think checkAnswer() could be a bit more specific. If this were a larger project, with different kinds of quiz questions, just telling your fellow programmer “Ya, this function checks the answer or whatever” might not be good enough. Does it check the user’s answer? In what context does it check the answer? Is there some background process “answer” that it’s checking? As Clean Code tells us, as programmers we want to use Intention-Revealing Names. That is, we want to show the reader why this function exists and what it does. Let’s try to clean it up now:
To my mind, this small update significantly improves our program. Now, when other coders come across checkUserAnswerForCorrectness(), they’ll clearly see that it takes in a MouseEvent from the user and checks to see if that answer matches the data in our database. This small change might save our team members valuable time.
Astute readers may have noticed that I also replaced the prev variables with previous. Although most people would have gathered what prev was short for, I made this refactor for a very important Clean Code reason: Avoid Disinformation. Being clear means being specific, and we wouldn’t want our fellow programmers coming across prev and thinking it could stand for anything other than previous. While programmers will likely always use an i for iteration or an x to hold a particularly obvious bit of data, writing out full words should help you in the long run.
Although being verbose in your naming conventions is important, writing clean code requires balance. You can’t just go naming your function something like this:
While this is technically a more specific name for this function, it’s obviously worse than checkUserAnswerForCorrectness . We can’t even see the whole name of the function, let alone any arguments it takes in! Our programs are stories, and as storytellers we would do well to build up our descriptive skills. While there are many more lessons in this chapter of Clean Code, this is a good primer on using effective names.
Comments
Simply put, programmers cannot rely on comments to save their messy code. As Uncle Bob says, nothing can be “quite so helpful” as a well-placed comment, but it can also clutter up your programs the more you use them. While it might be useful to provide your reader copyright information or explanation of intent in the form of a comment, on the whole comments are unnecessary and distract the eye away from the code, the ultimate source of truth in your program.
I’ll admit, I’m actually pretty good about avoiding comments. The programmers that taught me consistently instructed me to express myself in code, and that comments are mostly frivolous. More than likely they taught that because they read Clean Code before I did. To stay true to this blog post I’ll insert some comments into the app and share some of the important lessons from Clean Code. We’ll first take a look at the following bad comment:
The above comment is a good example of what Clean Code calls a Redundant Comment. Does the comment even do anything for the reader here? Wouldn’t your program be clearer if you refactored the function name to be more descriptive, perhaps naming it something like provideNextQuestionToUser() ? Ultimately, you don’t want a comment — which is supposed to impart understanding — to take longer to grok than the function itself, so this is an easy comment to avoid in the future. Let’s look at another kind of bad comment:
The above comments represent what dear Uncle Bob calls Noise Comments. They pepper poorly-written functions, bloating your code until you can hardly follow it. While a programmer may want to include one comment at the top of a function to guide the reader, using good naming conventions can save several lines of comment fluff. Just see how much cleaner the code is when we cut it down a bit:
I think we can agree this is significantly easier to read, and your fellow programmers will likely appreciate the top comment describing what the function will do. Remember, before you write a comment, see if you can refactor your code to make it clearer. Let’s look at the last bad comment we’re going to examine here:
Hopefully this is somewhat obvious, but Commented-Out Code has virtually zero usefulness to other people reading your programs. Maybe the above code was for an earlier iteration of the app, maybe it’s just cruft that an inattentive programmer forgot to delete. Regardless, it probably shouldn’t exist in the program, and because it carries so little information, it’s likely to persist. As Clean Code tells us, other people likely won’t have the courage to delete this comment because they don’t know if it’s important. As the initial writers of our programs we should pay close attention to what can be excised from our programs to make them clearer. Comments can be useful, but only when done well.
Over the next couple of weeks I will be reading more of Clean Code and sharing what insights it has for budding programmers. By reading this book very slowly (roughly one chapter/week), I want to really absorb as much information as I can, ultimately making me a significantly better programmer overall. Check back here weekly to see my progress!
Reading Clean Code: Week 1 was originally published in Level Up Coding on Medium, where people are continuing the conversation by highlighting and responding to this story.
This content originally appeared on Level Up Coding - Medium and was authored by Jacob on Software
Jacob on Software | Sciencx (2021-06-27T00:00:25+00:00) Reading Clean Code: Week 1. Retrieved from https://www.scien.cx/2021/06/27/reading-clean-code-week-1/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.