Introduction
In this post, we will describe one of the topics that most debate raises among developers when they are dealing with the issue of clean code.
Many developers think that comments are good practices while others think totally the opposite, that is, to apply comments are bad practices.
Sorry to tell you that there are no absolute rules, everything depends on the case. The truth is that there are a number of cases in which the comments do NOT contribute to software development because they have been replaced by other tools that perform that function better than that of applying comments. In other cases, comments may cause noise to the source code that we are developing, or that we will be reading in the future. Therefore, in those cases, the ideal is to have no comments.
On the other hand, there may be cases in which comments are good practices, such as the documentation of a public API in which to learn the behavior of a library, but not how it is developed.
In the next post, I will describe several practices in which comments produce noise and should not be applied in your code so that your code grows in quality.
Only comment things that have business logic complexity
Comments have to exist only to help programmers in explaining business logic that is complicated for programmers to understand. In no case, the comments describe the algorithm. We have to think that a good code is most of the time self-documented and therefore, the source code is understood with the fact of being read. Comments are an extra, not a requirement.
However, it can happen that in the algorithm there is a specific business logic that we do not know as developers. For example, operations with credit cards, with own insurance operations, etc. The following example shows the verbosity and unnecessary comments in most of them. However, the last comment would not be irrelevant since an operation is being carried out in the domain of the problem we are modeling and it would not hurt that this comment existed. This comment is not describing what is being done at the programming level but at the level of business logic.
function convert(data){
// The result
let result = 0;
// length of string
const length = data.length;
// Loop through every character in data
for (let i = 0; i < lenght; i++){
// Get character code.
const char = data.charCodeAt(i);
// Make the hash
result = (result << 5) - result + char;
// Conver to 32-bit integer
result &= result;
}
}
The equivalent code would be the following, in this code it is observed that the comments did not add value, but produced noise to our code.
function convert(data) {
let result = 0;
const length = data.length;
for (let i = 0; i < length; i++){
const char = data.charCodeAt(i);
result = (result << 5) - result + char;
result &= result; // Convert to 32-bit integer
}
}
Don't have journal comments
The comments as a journal were, and I hope it is not today, a tendency to know what had happened to the file over time. This could make sense in the past for lack of version control tools.
Today, this task should be delegated to version control software (I recommend using GIT). Therefore, there is no need for dead code, commented code, and especially journal comments.
To obtain this information you would only have to use the git log
to get history command.
Below, there is a code with journal comments versus its cleaner version.
/**
* 2018-12-20: Removed monads, didn't understand them (CC)
* 2018-10-01: Improved using special mondas (JS)
* 2018-02-03: Removed type-checking (LI)
* 2017-03-14: Added add with type-checking (CC)
*/
function add(a, b) {
return a + b;
}
function add(a, b) {
return a + b;
}
Avoid positional markers
You should avoid positional markers because usually just add noise.
Let the functions and variable names along with the proper identation and formatting give the visual structure to your code.
The following code shows an example with positional markers and its clean version. You should think that these techniques of using comments are anachronistic from other times in which there was less tooling for developers. Nowadays, it is not necessary to create these marks in a source code, since they are only noise.
///////////////////////////////
// Controller Model Instantiation
///////////////////////////////
controller.model = {
name: 'Felipe',
age: 34
};
///////////////////////////////
// Action Setup
///////////////////////////////
const actions = function() {
// ...
};
controller.model = {
name: 'Felipe',
age: 34
};
const actions = function() {
// ...
};
Conclusions
Comments are one of the most debated topics today by developers. Many developers believe that they are necessary and others that are not, extremes are never good in any decision in this life, and software development is no different.
Therefore, in this post I have tried to summarize three practices that make the code dirty by including comments. However, if we are creating a public API it may be interesting to write comments since we are documenting the API.
A bad practice applied by many teachers is to comment on each of the lines in production codes. This bad practice is inherited from when a junior programmer is being taught to code code, each line is commented on as a study guide.
However, the difference between having a study guide and commenting on each line of code in a production development is huge.
Finally, the points we have addressed are the following:
- Only comment things that have business logic complexity
- Don't have journal comments
- Avoid positional markers
Top comments (7)
Absolutely this.
I would rephrase
to
Because there may be cases where
you have (mathematical) knowledge which the future reader of your code might not have
your code isn't correct but a smart approximation which is good for now
your code isn't correct and no approximation to anything but for reasons outside the code it is written like that. I actually did this where data was sometimes deliberately overwritten with null which was wanted behaviour. So I commented this as
//Customer decision: do this and that else null the value
And when a furture reader stumbles over this line of code he saves time not discussing this point any further
While comments on every line are definitely an eye sore, aren't positional markers a tool to improve readability and grouping of code? I'm admittedly a junior/mid-level dev, but have received complements for the way that I have utilized positional markers in my code/scripts. I want to add that I didn't care for the way the positional markers were styled here but overall I think they improve readability for other users.
Far too often, I see zero commenting in code. If there had to be one extreme or another I would prefer verbose code commenting, particularly in larger development teams where a significant number of junior or developers new to the team will be reviewing code and do not understand business logic and process context.
My rule for code comments is this: comment only on the 'why' never the 'what', unless the 'what' is a regex, in which case you can comment the hell out of it :P
I agree with all the points, except the part that states that comments should only be used when there is 'business level complexity'.
Don't get me wrong - I'm not advocating using comments to the point of the example - that definitely should be avoided at all costs. But it also seems like a rather extreme case.
Personally I add comments to code like javascript one-liners that are almost equivalent to machine code when it comes to readability, or functions that seem simple but have more use-cases than meet the eye.
Just adding my thoughts to the topic :)
I love adding the occassional
todo:
comment, when I'm busy and see something that needs improved. Usually it is outside of the current task I'm working on, so I'll note it and move on.Thanks for sharing this serie. I'll improve my code right now. Saludos :D
Thanks Jabin! 😜😜
Muchas gracias 🙃