Simple and Clean: Electric Boogaloo
..is the way I want my code to be written, but it’s hard to actually do it without knowing what it is.
“Hey, this looks familiar!”
This article is somewhat of a rewrite of my other article, which discusses clean code. I’ve (attempted to) rewrote this article, and also add some other things I’m missing, so I hope this article can explain better and give examples to the implementation of clean code.
What is clean code?
Clean code, from what I can gather, is a code that is easy to read and easy to change. On the surface, it seems very easy to understand, but the truth is, it is something that you need to practice, as it can benefit not only yourself but also your coworkers and other people that might read your code.
Implementations of clean code
Implementing clean code can be quite challenging, especially if you’re used to writing code with a result-oriented mind. I myself am also at fault for doing this, as for the past four or five semesters, I code with the mindset of getting the best results possible and not even caring about how the code looks.
Here are some things you can implement in your code to make it cleaner:
Meaningful Names
The names of your variables and class should be quick to understand and don’t sound ambiguous. It must be descriptive and also easy to pronounce and search. For example, you’re working in a store, and the list of items that are sold in the store is stored in a variable called items. But, you also have a storage with their own items. Therefore, it’s better to distinct the items sold in the store from the items in the storage. You can change the items variable to something like store_items.
For example, look at this snippet of code in views.py:
Those functions immediately tells us that this function deals with the views for updating and deleting a project, so when something goes wrong in that section, we can immediately check if these functions are working as intended. Speaking of functions...
Functions
Functions should be small and only do one thing and one thing only. It shouldn’t attempt to do multiple things at once. It should be written as clear as possible so that it wouldn’t confuse other people if they want to change the function.
This function, for example, works to create a dictionary of the submitted data only if the form is valid.
Comments
Only comment whenever necessary and make it concise and understandable. Comment a code when you want to explain or clarify the code’s intention, and you can also use comments to add warnings to a code. Let’s take a look at the previous code snippet. As you can see, the comment explains what the function does so when someone reads it the first time, they can have a better understanding of what it is.
Also, don’t comment out a block of code. Just delete them.
Consistent Formatting
Making your code consistent makes it easier to read in the future, and you’re less likely to track back to see if you missed something. Good formatting can also make your code more pleasing to look at. Small things like whitespace, indentation, and code placements might doesn’t affect the function of a code, but they can help you to read it much faster than an unformatted code.
Also, do note what language you’re using, as different languages have different naming conventions. For example, Python uses snake_cases_like_this, whereas in Java you might use CamelCaseLikeThis.
Clean code in our project
pylint
In our project, we implemented pylint to make sure our code is as clean as possible. Pylint takes care of things such as the order of imports, whether a line is too long or not, whitespace, naming convention, and other things that can create code smells. In short, pylint helps us to make our code consistent in format. Every time we push a commit to GitLab, we make sure our pylint score is perfect.
sonarqube
We were also provided with Sonarqube to also keep track of how clean our code is. Not only is sonarqube checking for code smells, but it also checks for bugs and security issues. It also checks for duplication and code coverage. This is a handy tool to use, especially in terms of duplication, as it can be easy to miss and tedious to check.
Conclusion
Keeping your code clean is always good to do. It allows for better readability, faster bug fixing, and overall better quality of life when you code. There are also tools that you can use to keep your code clean, so do try to use them in your project. Hopefully, this article helps, and I hope your code will always be clean. And simple, hopefully.