Why should I comment my code ?
If you're actually code in Java, JavaScript, Python, PHP. You're probably hear about technical documentation and some things like :
And if you had not heard anything about "how to comment your code". So you were, you are or you will be confronted to THE question :
"What this code do ???"
And you know how it's painful when something doesn't work and you can't understand WHY !
When you use an external program, your reflex is to read documentation about this program to understand how to use this.
When you comment your code, the objectives is the same. You'll write some details for you in the future or for the people who use or improve this code.
Objectives
The objectives is multiple, just think about you in 2 years in this code. You'll be happy to see somes comments who explain what is this weird classes you added before 😆.
Now, if you don't code alone. Think about you're associate will read and use your code.
And PLEASE, think about all people who use your code in the future if you're make an open source program.
I think you understand now, when you comment your code you actually :
- You saves time for you, and for other peoples
- Describe, and have a readable code
- Your code will be accessible
When should I comment ?
It's recommended to comment your class, you're function and use inline documentation when is necessary. I think it's the minimal requirement for a readable code.
A code has commented, is a readable code. BUT, use comment whith thriftiness.
Of course, if you're function is named
sumfor example, and take two arguments. It will be really simple to know what the function do.
Personaly I think you should comment for function when the function is over 10 lines, and it's required for classes.
And please remember, a developer does not only code.
A developer maintain, debug, keep an eye on evolution, document, and think how to resolve problems.
So please, comment your code and make happy the "you" of tomorrow and all people who read your code. And you'll make a step to become a programming god 😃.
Tell me if you have any suggestions, or remarks and of course if this article was interesting.
There is so much to say about this, feel free to express your point of view, so don't hesitate. 😜
Top comments (17)
Actually, please don't comment your code (public API notwithstanding). Write code that is either easily testable (or even the tests themselves!), and easily replacable.
I don't need to read your novelization of what your code does. I need to be able to rewrite it in a fashion that I understand, or make changes in the right place.
The only code that needs comments is code that makes no sense at face value.
+1. I get the idea behind author's post, but usually comments are kinda annoying to me. Either because the code is already self-explanatory and the comments are redundant, or because the code could be refactored to be clearer instead of having to explain it through comments.
I don't totally agree with this view, and I fully understand everyone's different points of view on this sensitive issue.
Nevertheless, if we assume that the code is explicit enough. Then it would be easy to code for everybody, and we have to keep some reference points that will help anybody to understand our code (*nobody *codes without a minimum of reference points).
Besides, the idea is not to make a "novel" but to describe quickly in one line the final goal of the few lines written. And as I said quickly, I don't want to write constantly but use this tool properly to make the reading more pleasant for everyone.
You mention „readable code“ produced by comments. I would say if you need comments to make your code readable, it isn’t exactly this in the first place. You have unreadable code.
I would always aim at readable code and comment only spots where they help reducing time to go through a complex peace of it. If for whatever reason your code must be in a form where humans cannot understand it, tell me what went wrong in the first place?
What is a readable code, and what is an unreadable code?
Always the same problem, a code that is readable for one may not be readable for another. There is no such thing as code that everyone will understand because we have deduced that it is readable.
The goal is as I said to have reference points allowing everyone to find their way.
Of course, we should not generalize and use this tool sparingly. But knowing how to use this tool is a real asset for everyone.
I cannot agree on that. Let’s take the English language as a common way to understand code. Anyone who can read English, can read code consisting of English words. So why not use actual words. Only cut words where necessary or form abbreviations if it cannot be avoided. I would claim this brings us pretty close to everyone understanding it. Of course, an hour, week later I might choose a better name. But at that very point in time it was my best take. So maybe 2 years later I might be like “yeah, that could be named better” but not necessarily not understanding it at all.
If you stick to a personal code why not.
Use abbreviations for you: ok. But to assume that EVERYONE will understand you is utopian.
You just have to realize that you are not alone, that some will understand more easily than others. That this tool exists, and that it is necessary to use it as it is necessary.
But the fact that one cannot please EVERYONE does not mean that I should not write human readable code where applicable. And you are right - realise that you’re not alone. Stop writing code only you understand or a small elite group. Make it accessible to the majority. At least to EVERYONE able to read English.
This reminded me of a fantastic talk called The Art of Code Comments. The main philosophy is to use code comments for the "why", not the "how". It gives some really nice examples.
That's really interesting, thank you for that !
I understand where you come from, Robin. However, I used the word human language, not English. I agree that hundreds of millions of coders are not all that familiar with English, even though most programming languages use it as a basis.
It has nothing to do with being nationalistic or not. It's about being practical. Language barriers will be with us for at least another 50 years, if not much longer until linguistic AI works 110%. Whether you are a Mandarin, Hungarian, Zulu, or Inuit speaker, use your own language properly to communicate as efficiently in that language as you are trying to do in the programming one. That's my only message.
Where I work, we use JIRA to track issues, and every commit message starts with the JIRA ticket ref so commenting the why of it is largely unnecessary. Very very occasionallly you'll see people commenting the how of it, as in how to make use of this method if it's somehow impossible to write it using clearer, cleaner code.
Yes, that's the message I'm trying to get across.
When you take a code that is not yours; you're going to spend time understanding what this X function does, and how you can use it for example.
It's a real benefits.
Hello Tykok,
thank you for your article.
I like the general mentality of commenting code when commenting helps.
I imagine that "when it helps" is an issue in and of itself, since it allows bad code to go uncommented.
"Comments introduce ambiguity and can be misleading as well as increase maintenance costs." - True.
It is true, yes. But Only when the dev is not capable of using "strongly typed"/ explicit descriptions when using human languages, properly. That's how ambiguity is created in the first place, in any language.
Just as we need to tell a CPU exactly what to do, we need to be able to practice the same skills to inform humans exactly what we mean.
Now is the time to either thank your school's language teachers, or go back and study more on how to use human languages.
Totally, you have to know how to use this tool and be aware of it.
Some comments may only be visible to logged-in visitors. Sign in to view all comments.