Introduction
In the last two posts 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 find out that a function should be short, to 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 to read this book and write better code.
What next?
In this article we will talk about comments in our code and code formatting. The scope is to try to find out when we should add comments in our code and how this comments should look like. Because developers needs to read code every day we need to use a good formatting style that helps developers to read the code as easy as possible.
Let’s start with code comments.
Comments
When we are things about comments in code we have in mind comments that explain what code is doing. The problem with comments is that is not all the time updated. Very often the code is changing but the old comments remain the same. In the comments don’t reflect anymore the code.
In time, code is moved from one location to another, is refactored, spited, 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 to understand that comments are part of the code. And, in the moment when code is changing, the same thing should happen with comments. But because of time pressure or indifference, we end up with outdated comments that don’t reflect reality anymore.
We need to think at 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.
Bad example of comments
Ugly code
Often comments are used in locations where code is ugly and is 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 express what you are doing there.
Code explanation
When you have a code that cannot be understood, than comments is not a solution. Try to rewrite a 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.
Mumbling
Adding comments into the code only because you think that is necessary is a bad thing. Often it’s happening that somebody add comments in code only because he think 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.
Redundant
When you have a good name for your field or method, that you don’t need anymore a comment that describes what is the scope of that field of method. For example a methods that is named “SendEmail” don’t needs 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 say “The value for the current order is stored”. The comment in this case don’t adds a valuable information.
Misleading, Mandated and Noise
In many cases, developers don’t express what they intended to do. Because of this you can end up with a comment that say that an email is send to customer, but you end up debugging and try to understand why email is not send.
In the end you realize that the method that is called under that comment don’t send an email, only construct 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. 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 is the scope of a constructor. In general, constructors should never be commented.
Journal
30 years ago, when source control was not use on any project maybe it was a good ideas 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 mechanism 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.
Good example of comments
Yes, there are cases when comments are useful and can add value to our code.
Legal and Informative
There are cases when you need to add a comment because of the legal reason. Code is under a specific license terms and needs to be specified. In this case you should add a comment that specify 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.
Intension and Clarification
A comment is all the time useful when intention is expressed. It is not important to comment what we done in the code, because the reader can see the code its felt. It is more important to explain what we wanted to do in the code.
There are cases when we cannot express exactly what our intension is. Because of this we need to add comments that add more clarification and explain why we don’t a specific action. Maybe there is a bug in an external library that we had to avoid or client had an odd request.
Amplification and Warning
There are time when we know that some lines of code are very important, and without them the application could crash for example. In this cases, comments could warm other developers about the importance of that 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.
API Documentation
All public API, that is intended to be used by external clients and developers should be documented very well. Because 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.
Formatting
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 may 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 times 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 recommendation 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.
Variables
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.
Fields
You want to group all the fields in the same location of the code. Field with different attributes should be grouped together (visibility, scope – static/non-static, const. and so on).
There is another trend, that say that you should group all the elements of a class based on functionality and where 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
Functions that are dependent should be place together. It is recommended to have the child function under the function that call it. In this way you will be able to read the code very easily, without having to navigate between different places inside the code too much.
Code Affinity
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 a specific functionality.
Indentation
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. Respecting 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 easily to respect the same indentation everywhere.
Coding Style and Formatting
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 try to lose days on code formatting and style. There are plenty of this rules already available that can be used with success – don’t reinvent the wheel one more time.
It is important to know that different team 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.
Conclusion
Comments and code formatting can make a code more readable and easily to understand. Try to define this rules and the beginning of the project and be prepare to change them if is necessary and if it makes sense.
Don’t forget that the most simple rules are the best one!
In the last two posts 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 find out that a function should be short, to 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 to read this book and write better code.
What next?
In this article we will talk about comments in our code and code formatting. The scope is to try to find out when we should add comments in our code and how this comments should look like. Because developers needs to read code every day we need to use a good formatting style that helps developers to read the code as easy as possible.
Let’s start with code comments.
Comments
When we are things about comments in code we have in mind comments that explain what code is doing. The problem with comments is that is not all the time updated. Very often the code is changing but the old comments remain the same. In the comments don’t reflect anymore the code.
In time, code is moved from one location to another, is refactored, spited, 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 to understand that comments are part of the code. And, in the moment when code is changing, the same thing should happen with comments. But because of time pressure or indifference, we end up with outdated comments that don’t reflect reality anymore.
We need to think at 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.
Bad example of comments
Ugly code
Often comments are used in locations where code is ugly and is 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 express what you are doing there.
Code explanation
When you have a code that cannot be understood, than comments is not a solution. Try to rewrite a 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.
Mumbling
Adding comments into the code only because you think that is necessary is a bad thing. Often it’s happening that somebody add comments in code only because he think 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.
Redundant
When you have a good name for your field or method, that you don’t need anymore a comment that describes what is the scope of that field of method. For example a methods that is named “SendEmail” don’t needs 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 say “The value for the current order is stored”. The comment in this case don’t adds a valuable information.
Misleading, Mandated and Noise
In many cases, developers don’t express what they intended to do. Because of this you can end up with a comment that say that an email is send to customer, but you end up debugging and try to understand why email is not send.
In the end you realize that the method that is called under that comment don’t send an email, only construct 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. 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 is the scope of a constructor. In general, constructors should never be commented.
Journal
30 years ago, when source control was not use on any project maybe it was a good ideas 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 mechanism 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.
Good example of comments
Yes, there are cases when comments are useful and can add value to our code.
Legal and Informative
There are cases when you need to add a comment because of the legal reason. Code is under a specific license terms and needs to be specified. In this case you should add a comment that specify 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.
Intension and Clarification
A comment is all the time useful when intention is expressed. It is not important to comment what we done in the code, because the reader can see the code its felt. It is more important to explain what we wanted to do in the code.
There are cases when we cannot express exactly what our intension is. Because of this we need to add comments that add more clarification and explain why we don’t a specific action. Maybe there is a bug in an external library that we had to avoid or client had an odd request.
Amplification and Warning
There are time when we know that some lines of code are very important, and without them the application could crash for example. In this cases, comments could warm other developers about the importance of that 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.
API Documentation
All public API, that is intended to be used by external clients and developers should be documented very well. Because 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.
Formatting
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 may 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 times 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 recommendation 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.
Variables
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.
Fields
You want to group all the fields in the same location of the code. Field with different attributes should be grouped together (visibility, scope – static/non-static, const. and so on).
There is another trend, that say that you should group all the elements of a class based on functionality and where 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
Functions that are dependent should be place together. It is recommended to have the child function under the function that call it. In this way you will be able to read the code very easily, without having to navigate between different places inside the code too much.
Code Affinity
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 a specific functionality.
Indentation
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. Respecting 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 easily to respect the same indentation everywhere.
Coding Style and Formatting
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 try to lose days on code formatting and style. There are plenty of this rules already available that can be used with success – don’t reinvent the wheel one more time.
It is important to know that different team 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.
Conclusion
Comments and code formatting can make a code more readable and easily to understand. Try to define this rules and the beginning of the project and be prepare to change them if is necessary and if it makes sense.
Don’t forget that the most simple rules are the best one!
“Don’t comment bad code—rewrite it.”
—Brian W. Kernighan and P. J. Plaugher1
Comments
Post a Comment