When I read Clean code by Robert C. Martin, I realized I should have read this book years ago, probably in the first year, I start learning to program, because the book contains techniques to write code that is easy to maintain and understandable (especially by other developers) and also points out some mistakes in the code examples that I made too. However, write clean code requires practicing and I was wondering if among all that techniques there are some that are easy to apply even if you are at the beginning of your journey to becoming a software developer. So I came up with four:
Meaningful names
The task we frequently do is name things: files, variables, methods, etc. And sometimes is hard to find a good name, to make it easier to use intention-revealing names, so when anyone read it will understand it.
Take this variable, for example:
let u;
Can you tell what the variable u stores? Probably not because the name u reveals nothing, what about now:
let activeUsers;
That’s a better name because we read it and understand the intention to stores active users.
Another example:
function getUsers() {
// … some code here
return users.map( user => user.status === ‘active’)
}
When you read the function name you understand that the function return users, but when you look at the implementation you discover that the function returns only the active users, a better name would be getActiveUsers because it reveals the full intention of the function.
Small functions that do one thing
How many times did you come across 100 line functions? Well, I have and some of them were written by me. Chances are that those functions are doing more than one thing, you may ask how I’ll know if a function is small enough? What I do is to give an intention-revealing name to it, and that name will tell me if the function is doing more than one thing, if so, I break the function into other functions that do different tasks, and consequently, the functions will become smaller.
For instance, imagine a function that receives a list of users as an argument, then for each one validates its data, send an email and save it in a database, the intention-revealing name for this function would be something like:
function validateAndSendEmailAndSaveUsers(users) {
}
Now it’s easy to know that function is doing more than one thing, next step is to break it into more single-purpose functions:
function validateUserData(user) {
}
function sendEmail(email) {
}
function saveUser(user) {
}
Avoid using comments
I know, this one is controversial, there are cases where comments are necessary and there are cases where it's not. I want to focus here on the type of comments used to explain a piece of code, like this one:
// check if you are eligible for the discount
function check() {
}
Usually, this type of comment is a sign that the code is not intelligible, so when this happens, and I did it a lot in the past, you should take the time to analyze the code and see if there is a way to improve its intelligibility. The previous example, personally, I prefer like this:
function isElegibleForDiscount() {
}
Try to use code to express yourself instead of comments.
Single-responsibility classes
Probably you have heard of the single responsibility principle, it’s a principle easy to understand, “a class should have one, and only one, reason to change”, therefore only one responsibility. However, for some reason, we still come across super classes with many attributes and methods. Perhaps some developers think that a system with a few large classes is easier to understand, but is the other way around.
Take a look at the classes you wrote, identify their responsibilities, then for each one create another class to handle it, you’ll end up with a system, with more classes but smaller than the originals, easier to understand and to maintain. Seriously, have you tried to understand an 800 lines class, maybe you have succeeded but didn’t you wish that class were smaller?
I tried to keep it short, I hope those tips help you in your journey and I really recommend reading the Clean Code book to delve deeper into the subject.
Top comments (2)
These techniques appear very basic to me.
And I disagree about not using comments.
First, because there are doc-comments that automatically will be compiled into an API-Documentation. Second, because there are cases where you have to traverse specific data structures that result in code with 2 to 4 indentation levels (and therefore are hard to understand). By Using comments, you can help yourself and other programmers to understand, what this portion of your code does. Therefore you and others can skip this portion (in a manner of not having to deeply understand, what this traversing logic does), whilst trying to extend or fix other parts of the code.
Yes, those are techniques for those who are learning to code that I wish I knew back then. And I agree, there are cases where comments are necessary.