Most of the developers had the approach of “it is fine as soon as it works” at the very early stages in their career. However, after some experience and joined a team, they had this feeling that it is not that easy. In present, the big projects are written by a number of people, a team which is pretty dynamic. In order to protect the dynamism of the code and expand the project by another developer, it is crucial that the code must be understandable; and this is called “Clean Code”.
Even though it sounds very simple to say that clean code is maintained by a set of standards, actually the essence is the discipline of the developer. From the beginning of the project, the developers in the team must agree on some standards and stick to those rules so that the future complications would be prevented. Moreover, the standards must be universal so that a new developer would be able to follow easily. In a nutshell, if you would like to expand your project, you must keep it clean.
What is wrong with smelly code?
Let me put it this way: Imagine the situation where you have a disorganized worktable and it is not that messy so you think that it is fine to tidy up later. You continue working and the desk became messier; you though you would handle it later, and so on and so forth, at the end you have decided to re-organize it but you have a deadline coming up. You started a little bit but then you had to work; but the desk had become messier than ever. Now you realize that there is no possibility that you would be able to clean up your desk without taking time off from work. Next, you stopped working, gave your all attention and time to your desk but the problem is so big you have no idea what belongs where and you need another pair of hands. You begged your roommate for some help, and stole their time to organize your desk. Unfortunately, since you had stopped working on your project, another application had developed all of the features you were planning to do, at the end of the day, you had end up at a messy desk with financial and moral loss.
This is what the smelly code will cause. You may believe that you took the situation under control for some time; however as soon as the project gets bigger and gets more complexed, the messiness of the code will also increase and extremer. Eventually, the developers on the project will end up sparing some time just to revise the existing features rather than developing new cooler features. When there is a new team player or during the Code Review sessions, a huge time loss will appear in order to understand what you meant with your code.
In summary, if the discipline of writing clean code is not gained before starting the project, the smelly code will be the biggest pain in the neck.
How to recognize the smelly code?
It is easy. It smells so bad you just know it. Smelly code raises a eyebrow, confuses the reader and creates the question mark on their head.
Difficult to understand
Not open the extension, modification is required for new features
Hides the intention
The objects are tightly coupled, and dependent on each other.
Why developers write smelly codes?
In order to become a good coder, the experience is the key; but i think that coding is not the only essence to become a good coder. It would be enough to understand what is the good, clean code. This experience is gained by reading the examples of clean code of other developers and paying attention to code review sessions. With these two methods, a developer will know that their code has some bad smell coming off and how to get rid of it.
Even the experienced developers may write smelly codes sometimes, this is mainly because of the deadline pressure coming from the upper management. If there is no time to review the code and make necessary adjustments, it is going to stay as smelly because it does what is asked.
Sometimes, the developer may say that “I’ll fix it later”; and between you and me, this developer is mostly a liar. Because as Uncle Bob (Robert C. Martin) states
“Later equals never”.
What are the standards to follow for clean code?
When someone says “Clean Code”, the first book that comes to mind is definitily “Clean Code by Robert C. Martin”. I strongly recommend this book for every developer out there for a fun and fruitful reading. The topics are explained simple but also detailed. I will be briefing four chapters from the book which i believe that those chapters are the most essentials and good for step #1.
Naming
It is really challenging to find the most suitable name for variables, functions and classes; however choosing the best name is crucial so deserves some thinking.
The name must reveal its intension. For instance, when naming a variable we can use any word or any set of letters for our personal taste and the code will work; but it is not the right thing to do. For example, keeping a count of process, you can choose “myVar” or “count” names for the variable but when you name it “count” the reader will immediately understand the purpose of the variable. For “myVar” it is not the case. It does not tell anything about the variables so the reader has to read the implementation and sometimes, the implementation is not also intention-revealing.
Each programming language has their own convention when it comes to naming. The most common one is that name variables and methods with first letter in lowercase; and uppercase for the classes. However, in GoLang, when the first letter is uppercase it means that a variable is public; and private if lowercase. So starting the name of a variable, that will be accessed by publicly, with a lowercase because it is a variable will cause some serious problems.
You do not need commends to explain the name. The name should be giving the information itself.
Avoid misinforming while naming. The name must be clear and precise; it should not declare anything that is not relevant.
Keep your names as short as possible. The longer a name is, the more confusing the name is. You are able to choose a name which will be spread entire IDE; but why you would like to do that (Rhetorical question, I know that you do not want that)? It does not help anybody. Instead of using the name “theUniqueAndVerySpecialCounterWhichWillKeepHowManyTimesAnotherSpecialVariableIsProcessedButNothingButStillCrucial”, you probably be choosing “updateCount” which is even cuter.
Avoid from abbreviations. Nobody will have time to encode the name “conn” if there is no information about it. Bu “mongodbconnhost” is much more informative.
Last but not least, name similar concepts similarly. When reading the similar names, our super brain will make the connection between them. If you used “Teacher” while naming, use “teacher” keyword to name similar classes. For example, “TeacherController” and “TeacherService” will tell us they are dependent on the Product object itself; however “EducatorController” and “EducationService” names will just confuse some heads.
Functions
Functions must be short. Some developers who works on huge projects will strongly defend that writing short functions is not always possible; however they will also agree with me on that big functions are not readable. The long functions tend to be divided into smaller function; but it is not easy to see it at first.
You only had one job... Do not let a function to carry all the burden which can easily be done by other functions. Let it have one and only one responsibility. Giving more than one responsibility to a function will increase dependency and it is against S of the SOLID design principles: Single-Responsibility.
Also, keep the argument list short. We may have a desire for long, complicated argument lists but do we really need it? Try to combine the arguments; check if you have a similar argument list also elsewhere. If so, this means that you can also use an object. For example, if you are using x and y coordinate numbers separately; notice that this is a Point so a Point object would solve all the problems. Also, in an ideal coding world, functions does have zero arguments; but we are realistic people, so keep it as short as possible.
Use verbs for naming the functions, because they do things.
Lastly, the functions must be side-effect-free. Imagine that your function will be used by another developer (which will happen probably). The other developer should not be worried about the exceptions or errors that may occur. You are responsible handling any exception and “null” returns. Please, do not return null, it is painful…
Classes
How you organize your classes is also important. Start with global ones: public constants and public variables. Then, write private static one, private variables and finally the functions (publics first).
Classes should be small just like the functions. Be sure that if it is possible to distribute the methods to other classes. Also, the long classes probably have too many methods or too long methods (or worse: both!). This is going to cause the code smell terrible and lose the logic of the design.
A class should have one and only one responsibility according to Single-Responsibility design principle. If you think that all of the methods in the class are there for that one responsibility, think again.
Comments
If you need a comment to explain your code, revise your code. It has be self-explanatory without comments.
Commenting code snippets will cause a dirtiness. If you don’t need this code snippet, why you have it written? If you may need it, then why comment it out?
You do not need to give too much information. “I wrote this code because I thought that bla bla bla..” We do not need those types or commenting because you and I are good developers; our code will tell the story itsef.
There is no need to comment the positions in the code. For example, writing “//// VARIABLES /////” above the variable implementations is none-sense because any one who has an understanding of what a variable is will know that you are implementing a set of variables by heart. Anyone who does not will not be reading your code, do not worry about non-developers.
The book “Clean Code” is a well-written guidance for those who would like to acquire a philosophy of writing clean codes. As addition, there four mottos which I found very catchy to know what a clean code looks like.
KISS: Keep It Simple Stupid → There is need to overthink. Keep your thinking basic.
DRY: Don’t Repeat Yourself → If you are doing a process more than once, try to write a method for it
DIE: Duplication is Evil → If you are re-writing the same lines over and over, take a good look.
YAGNI: You ain’t Gonna Need It → Do not build future features before it is asked. You probably won’t need it.
I hope this post gives you the urge to review that complicated code you were overthinking about and you keep your code as cleans as you can. I strongly recommend the book “Clean Code” for those who would like to deep dive. As addition, Clean Code principle is not something that you gain suddenly. It requires practice and experience on what a good and bad code is. My recommendation is to think at least twice how you can make your code simpler and if it is clean for other developers before submitting it. I wish a clean coding to everyone!
Resources
Clean Code — Robert C. Martin