In the last two numbers of TSM we discovered what kind of naming we should use for our methods, fields, classes and so on. Related to this we saw we should always use meaningful names that are related to the problem that we want to solve. Also, we saw that a method name should always express an action (start with a verb) and a class name should be always a noun (or to express a noun). After this, we talked about function, where we found out that a function should be short, do only one thing and the number of parameters should be limited.
All the information from this series is inspired from “Clean Code”, written by Robert C. Martin. I hope that in this way I will be able to make people read this book and write better code.
In this article we will talk about comments in our code and code formatting. Our purpose is to try to find out when we should add comments in our code and what these comments should look like. Because developers need to read code every day, we need to use a good formatting style that helps developers to read the code as easily as possible.
Let’s start with code comments.
When we think about comments in code, we have in mind comments that explain what code is doing. The problem with comments is that they are not always updated. Very often the code is changed but the old comments remain the same. So, the comments don’t reflect the code anymore.
In time, code is moved from one location to another, it is refactored, split, and moved. Even if the code location is changed, the old comments remain in the same location. In time, we end up with comments that don’t reflect reality and the code around them.
The hardest thing to do is to educate developers and make them understand that comments are part of the code. And, the moment the code is changed, the same thing should happen with the comments. But because of time pressure or indifference, we end up with outdated comments that don’t reflect reality anymore.
We need to think of comments like documentation. It is an expensive artifact that needs to be maintained. Because of this we should add comments only in location where it is necessary and code itself cannot express what is happening there.
Often comments are used in locations where code is ugly and they are used to ‘fix’ the code. Don’t try to make a code more beautiful by adding comments. When you have an ugly code you should refactor it and write it in a way that expresses what you are doing there.
When you have a code that cannot be understood, then comments are not the solution. Try to rewrite the code or rename fields and other elements in a way that the reader will understand the action that you are doing there.
In many cases, you can extract a method with a mindful name. The reader will understand very easily what is happening there based on the methods and fields name.
Adding comments into the code only because you think that is necessary is a bad thing. Often it happens that somebody adds comments in code only because he thinks that it is good, without a real background. In the end we end up with a lot of comments that are not useful and make code more difficult to read and understand.
When you have a good name for your field or method, you no longer need a comment that describes what the scope of that field or method is. For example a method that is named “SendEmail” doesn’t need any additional comments when it is called. It is clear from the name of the method that an email is send.
Another good example is a field called ‘vatValueForCurrentOrder’. From the name of the field it is pretty clear what value is stored in this field. You don’t need a comment that says “The value for the current order is stored”. The comment in this case doesn’t add valuable information.
In many cases, developers don’t express what they intended to do. Because of this you can end up with a comment that says that an email is sent to the customer, but you end up debugging and trying to understand why the email is not sent.
In the end you realize that the method that is called under that comment doesn’t send an email, only constructs the email object.
Usually in big companies and projects you end up with rules that require each method and class to have comments. You end up with a lot of comments that don’t add a real value. They are added by developers only because it is required. For example a property called “Id” had the following comment “Gets, sets the id of the current object”. No useful information is added by this comment, only additional 3 lines of comments that pollute the code.
What about commenting a constructor – “Construct an instance of object Foo”. Come on, it is clear what the scope of a constructor is. In general, constructors should never be commented.
30 years ago, when source control was not used on every project maybe it was a good idea to write in the code the journal of code changes (when, what, why, who – changed the code). But now, with source control and other tracking mechanisms, there is no point to do this.
Using a source control system you can see and track all the changes that happen on the code.
Position markers
Try to avoid using position markers into your code. For example adding
///////// into the code to find more easily a specific part of the
code.
Yes, there are cases when comments are useful and can add value to our code.
There are cases when you need to add a comment because of the legal reason. The code can be under specific license terms and this needs to be specified. In this case you should add a comment that specifies this thing, but without adding all the license terms to it. You can point from the comment to a specific document or url link that describes the license terms. You don’t want to have 200 lines of comments with this information
There are cases when a comment can add value to a code. For example when we give more information about what is returned by a method. Be careful that there are cases when a good name of a method can remove the necessity of comments related to return value.
A comment is always useful when intention is expressed. It is not important to comment what we have done in the code, because the reader can see the code itself. It is more important to explain what we wanted to do in the code.
There are cases when we cannot express exactly what our intention is. Because of this we need to add comments that add more clarification and explain why we didn′t take a specific action. Maybe there is a bug in an external library that we had to avoid or the client had an odd request.
There are times when we know that some lines of code are very important, and without them the application could crash, for example. In these cases, comments could warn other developers about the importance of those lines of code.
A good example is a mutex variable that is used to access a shared resource. Maybe not all developers would understand the importance of that mutex and a warning is needed.
All public API that is intended to be used by external clients and developers should be documented very well. Since they will not be able to see the implementation, the naming of different functions and classes in combination with comments should express very clear what the purpose of each method is and how it should be called.
Imagine that code is like the text from a book. It should be well
formatted, indentation to be used in the same way everywhere, after each
, to have a space and so on.
The most important thing when we are talking about formatting is not to respect a specific standard, but to respect the same standard everywhere. Even if you defined your own way of formatting it is okay as long as you respect that formatting everywhere. Code formatting should guide develops to read and understand the code.
Imagine a book that is written with 10 types of text style, different sizes, color and space alignment. It would be a nightmare. The same thing is applicable to code also.
Around this topic there are a lot of recommendations about how many lines of code a file should have, what is the optimal number of characters per line. You will not be able to find the magic number, but you will feel when the number of lines of code is too high and scrolling is annoying.
It is recommended to declare variables as close as possible to the location where they are used. You don’t want to declare a variable on line 1 and use it only from line 15.
You want to group all the fields in the same location of the code. Fields with different attributes should be grouped together (visibility, scope – static/non-static, const. and so on).
There is another trend that says you should group all the elements of a class based on functionality and where they are used. In this way you will have a zone in the file with methods, fields for a specific functionality. Even if the idea is pretty nice, it is pretty hard to read and change this kind of code, because very easily you can miss that a field is already declared for example.
Functions that are dependent should be placed together. It is recommended to have the child function under the function that calls it. In this way you will be able to read the code very easily, without having to navigate too much between different places inside the code.
The code with the same purpose and function should be placed in the same place. You don’t want to scroll or search in 10 files for a specific functionality.
It is very useful to respect an indentation standard in all your code, even if there are times when you want to break this rule. Obeying this rule you can easily spot a variable, the action executed by a FOR or IF clause and so on.
With the new IDE’s and tools it is very easy to respect the same indentation everywhere.
The most important thing in a team is to have a single formatting style that needs to be respected by all members of the team. Don’t waste days on code formatting and style. There are plenty of these rules already available that can be used with success – don’t reinvent the wheel one more time.
It is important to know that different teams may use different coding standards. Because of this developers should be open to accept and learn other coding standard, not only the one that is known by them.
Comments and code formatting can make a code more readable and easier to understand. Try to define these rules at the beginning of the project and be prepared to change them if it is necessary and if it makes sense.
Don’t forget that the simplest rules are the best one!
“Don’t comment bad code—rewrite it.”