Clean Code —Readable and Simple Code
What is Clean Code?
Here are some views of experienced programmers about clean code.
Clean code is simple and direct. Clean code reads like well-written prose. Clean code never obscures the designer’s intent but rather is full of crisp abstractions and straightforward lines of control. — Grady Booch, author of Object Oriented Analysis and Design with Applications
Grady viewed clean code as code that has low complexity, straightforward lines, and readable.
Clean code can be read, and enhanced by a developer other than its original author. It has unit and acceptance tests. It has meaningful names. It provides one way rather than many ways for doing one thing. It has minimal dependencies, which are explicitly defined, and provides a clear and minimal API. Code should be literate since depending on the language, not all necessary information can be expressed clearly in code alone. — Dave Thomas, founder of OTI
For Dave, clean code should be readable and upgradeable by other developers. It also has tests, meaningful names, minimal dependencies.
As we can see, they are has the same point on readability of code. So that, in order to write a clean code, we should (at least) make our code readable by others (and yourself too).
Actually, there are still many things that we should do in order to write a clean code. Keep reading to check them out!
Clean Code Characteristics
Meaningful names
- Use Intention-Revealing Names
Names that reveal the intent of itself shouldn’t be required any comments to describe its intent. The name l doesn’t reveals anything, since it required a comment to reveals its intent. Then, we should change the l into another name that shows its intent, such as lastModifiedTimeInDays.
- Avoid Disinformation
Programmers should avoid false clues that blur the meaning of code. For example, do not refer to grouping of students as an studentList unless it’s actually a List. Programmers have specific meaning of the word list. It wil be better to name it as studentGroup or students if it’s not actually a List.
Functions
- Small
Robert C. Martin said that lines shouldn’t be 150 characters long and functions should hardly ever be 20 lines long. Then, he said that functions should be 2–4 lines long.
For me, I agree that functions should be small, but I think that functions only need to be small enough so that you can understand what it does under 5 minutes. If we should take specific length of lines, I’ll go with 20 lines long.
- Do one thing
A function is doing one thing if it only does steps that are one level below the stated name of the function.
We need to make sure that the statements in our functions are at the same level of abstraction if we want to make sure that our functions are doing one thing.
- Use Descriptive Names
Function’s name should be represent what it does. Functions name don’t have to be short, so that don’t be afraid to use long descriptive name. With long descriptive name, we can also avoid using long descriptive comment.
It is worth to spend time for choosing a name of function since a descriptive names will clarify the design of the module.
Comments
- Comments Do Not Make Up for Bad Code
Clear and expressive code with few comments is far superior to complex code with lots of comments.
- Explain Yourself in Code
Rather than writing comments that explain what the code does, it’s better to express it in the code itself.
- Good Comments
Some comments are consider to be worthy enough to write, such as legal comments, TODO comments, and informative comments (such as explanation of regular expression statement).
Example
Here is an example of my code that i tried to write using some clean code characteristics.
The code above is used for cleaning data based on it’s type, folder or file. I’ll explain each function separately.
- Function cleaning_folders_data
As you can see, this function accepts one parameter, namely folders. If we look at the name of the parameter, we will think that ‘folders’ parameter is intended to hold a list of folder because of its suffix. With that, we already create a function with a meaningful name parameter. Besides that, the function name itself also a descriptive name because we don’t need to see the implementation code to know what will this function do when we called it.
- Function cleaning_files_data
This function accepts two parameters, the first one is to hold a list of folders, and the second one is to hold a list of files. In my opinion, those two parameters have meaningful name, because I just have to look at it once to know which type of data that this function accepts. Then, the function itself has a descriptive name since I don’t have to check the implementation code to know what this function will do.
I think, that’s all I can share about clean code. Thanks for reading this story! If you like it, check out my other stories! See ya!
References
Robert C. Martin. Clean Code: A Handbook of Agile Software Craftmanship.
