Clean Code — Naming
This week I moved on from automated testing to starting to study clean code. A few weeks ago, I was not at all interested in writing tests. I knew that I should be writing tests, but the execution was lacking. Now I know testing is one of the essential building blocks to writing great production code. While I was learning how to write proper tests, I spent some time reading as well. I started with The Clean Coder by Robert Martin. I would highly recommend this book. The book covers topics from why developers should lead with tests to how to interact with other teammates and stakeholders.
Here are some of my biggest takeaways from The Clean Coder on the topic of Test Driven Development:
- “How can you consider yourself to be a professional if you do not know that all your code works?”
- It’s easy to guess around at an answer to a coding problem and stumble upon the right answer. You shrug and say “well, if it works, it works!”, and move on. As professional developers, we must know how our code works and understand what it’s doing. The best way to do that is to declare the “boundaries” for how the code should operate by writing a test before the production code.
2. TDD provides a cycle for producing code.
- As I have said before, I like having processes I can follow in my workflow. The Red/Green/Refactor cycle is a great way to efficiently produce good quality code.
3. “The tests you write first are offense. The tests you write after production code are defense.”
- Writing tests after you have written the code is just confirming the biases you have already placed into your code. Always write your tests first.
While the book is titled The Clean Coder, it does not take much time delving into what Clean Code is. This is the topic that I have been studying the past few days and what I will be working on going forward.
So what is clean code? Clean code is efficient, human-readable code. Oftentimes, code is written that runs and works well for its intended purpose, but when the next developer comes in to look at the code, they are lost or they might need to spend a large amount of time getting up to speed on how the code works. Or maybe the code works but it only works if you run the code on a specific machine, in the Eastern Standard timezone, while standing on your head. The next developer to work on the project will probably find it easier and faster to scrap the project and start over.
Clean code should read as close to written prose as possible and this starts with naming things properly. Instead of declaring methods and variables with single letters or non-descriptive names, we should be naming them with names that illustrate their purpose and what they might accomplish.
i.e. var totalSalesTax = orderTotal * percentSalesTax is better than var tST = oT * pST.
Many people believe that if a developer needs to add comments in their code to document what is happening, the naming is not descriptive enough. Code that is understandable without comments or dedicated documentation is called “self-documenting code”.
What constitutes a good name? Does it have to be a long name? Not necessarily. Long names can be descriptive but they can also get confusing when there are other similar names. Take this example from “Uncle Bob” Martin in Clean Code: XYZControllerForEfficientHandlingOfStrings and XYZControllerForEfficientStorageOfStrings . These are both very descriptive names, but if they are used in conjunction with one another, it could be very easy to confuse the two. Human-readable doesn’t just mean a long name.
Does this degrade the performance of the application? Back in the days of punch-card programming, a descriptive name may have been a drag on the overall system. With the processors and computers we have today, this should not be a concern. Any performance hits will be outweighed by the benefits of having clean code.
What elements in the code get the special naming treatment? All of it. Professional developers should strive to name everything in their application descriptively. Tests should perfectly describe what they are testing. Variable names should state what they contain. Function names should be a good representation of what happens in the function. Even your commit messages should be descriptive and self-explanatory.
What are the benefits of proper naming? The benefits of proper naming can be boiled to more time, less stress, and more money! Understanding what each piece of the code does right away will allow you to quickly read through the codebase saving you time and the headache of testing each module. And we all know that time is money. The more time that can be spent writing new features and fixing bugs is more money in everyone’s pocket.
Here is some more reading material on the proper way to implement good names in clean code:
https://dzone.com/articles/naming-conventions-from-uncle-bobs-clean-code-phil
https://sourcemaking.com/refactoring/rename-method
More to come on clean code! Stay tuned.
