Three “Clean Code” tips that will make your dev team 50% more efficient
If I had to choose one point from the “Clean Code”, the bible of software engineering best practices, WE ARE AUTHORS would be it. The ratio of time spent reading vs writing is well over 10:1. Read that again. Slowly. We are constantly reviewing old code as part of the effort to write new code.
Since we spend so much time reading old code, it might be a good idea to invest a bit in making it simple and easy to understand, for us and our team.
Although I recommend reading the entire book, I find that the following three ideas are easy wins that can make a huge difference in your team’s productivity, efficiency, and most importantly — frustration reduction:
- Use Good Names
1.1. Intention Revealing: The name of a variable, function, or class, should tell you why it exists, what it does, and how it is used. If a name requires a comment, then the name does not reveal its’ intent.
1.2. Make Meaningful Distinctions: Don’t try to satisfy the compiler, If names must be different, then they should also mean something different. Imagine that you have a Product class. If you have another called ProductInfo or ProductData, you have made the names different without making them mean anything different.
2. Avoid Functions Side Effects
FUNCTIONS SHOULD DO ONE THING. THEY SHOULD DO IT WELL. THEY SHOULD DO IT ONLY.
With that in mind, we should avoid having side effects on our functions. Side effects are lies. Your function promises to do one thing, but it also does other hidden things. It can be making unexpected changes to the variables of its own class, or maybe modifying the parameters passed into the function or to system globals. In either case, they are devious and damaging mistruths that often result in strange temporal couplings and order dependencies.
Accordingly, in the example below, I would not expect the function to initialize the session, only to verify the password.
3. Comment Only When Necessary
3.1. Explain Yourself in Code, Not Comments: One of the more common motivations for writing comments is bad code. Which would you rather see?
This:
Or this?
Some more examples for bad comments that fall into the category of “trying to make up for bad code”:
- Redundant comments — it might take more time to read than the code.
- Commented-out code — please don’t do this. Others who see that won’t have the courage to delete it. They’ll think it is there for a reason and is too important to delete.
- Too Much Information — Don’t put interesting historical discussions or irrelevant descriptions of details into your comments.
3.2 Comments Lie: Not always, and not intentionally, but too often. The older a comment is, and the farther away it is from the code it describes, the more likely it is to be just plain wrong. The reason is simple. Programmers can’t realistically maintain them.
Code changes from time to time and might also be reviewed by team members before the change is committed. Unfortunately, comments sometimes fall between the cracks, forgotten in the past, still explaining something that just isn’t there. In addition, chunks of code can move from here to there, while their comments don’t always follow and become orphaned blurbs of ever-decreasing accuracy.
It is possible to make the point that programmers should be disciplined enough to keep the comments in a high state of repair, relevance, and accuracy. I agree, they should. But I would rather that energy go toward making the code so clear and expressive that it does not need the comments in the first place.
Truth can only be found in one place: the code.
To sum things up, if you want to dramatically improve your team’s productivity, remember and apply these three “clean code” principles:
- Use Good Names
- Avoid Functions Side Effects
- Comment Only When Necessary
