So We’ve seen people often suggesting to comment while coding. Let’s together find out what the comments are and how are they really helpful.
“Comments” are the text that is being added to the computer programs to better understand the implementation logic.
In technical terms, “ A comment is a programmer-readable explanation or annotation in the source code of a computer program.” (source: wiki)
There is a phase where everyone thinks that “As I’ve written the code I can better understand it !! so what is the need of commenting? “
Or
“Whom do the comments in my program help? “
Or to be simpler
“What is the use of writing comments? “
I’m gonna crack all these answers for you now…! :)
For instance, you’ve put your code in an open-source platform and users try to read it. What if they couldn’t cope up with the flow?
When we are writing smaller programs, it is okay to understand the code and logic with little hard work. But when we are trying to build larger applications where one file is linked to another or data is being rendered from other files, commenting can help you better understand the overview of code working.
The two important scenarios where comments help are :
- People who are referring to your code can easily go through the flow as the comments prevent one fight with the logic.
- You can understand your code when you read it after years (happens with most programmers ).
How should be the comments?
- Try to keep them relevant.
- Don’t write bigger comments, keep it short and simple.
- Don’t use it everywhere. ( Find the toughest code lines to comment).
For example, we are commenting an HTML file,
The comment should be in such a way that it should give a description (one line) about the tag and any ids or classes included in it.
So try to comment your code so that it helps for your future reference and also to those who are willing to refer your code.
I hope this helps you.
Do drop your feedback :)
Thank you guys. !
Top comments (31)
It's language/framework dependant and the old "Comment everything" is… getting old and poked fun at.
Modern languages, framworks and overall practice makes code much, much easier to read and understand. But I remember scientific code in C (or crazy ad-hoc languages): they are cryptic at best. So descriptive comments were necessary to decipher the thing.
For modern JS, Rails, Python etc. they should be only for the non obvious part and focus more on the "why". Typical exemple include what is returned by a required module or library, or why you wrote that helper function where it is used etc. But descriptive comments like "this function does that" should be a warning, if anything.
Yes. Exactly even I meant to say it !!
Identification of right places and intent to write a comment and keeping it clean and informative (like u mentioned in the last lines) is important...
Thanks for this comment :)
By the way I forgot, but a good README also greatly reduce the necessity for comments.
Yeahh .! 👍 It must clearly give the view of entire project!!
"Nothing can be quite so helpful as a well-placed comment. Nothing can clutter up a module more than frivolous dogmatic comments. Nothing can be quite so damaging as an old crufty comment that propagates lies and misinformation" - Clean code by Robert C. Martin.
Basically you need to be very aware of how and what you comment. I am very much against mandatory comments. It can clutter up code and at best provides double information like Benito pointed out at worst provide information is outdated because the code is updated but the comments aren't.
Personally, as a rule of thumb, I comment on public methods of interfaces. They should adhere to the open/close principle anyways so the comment on the interface should remain up to date. I make sure I name my variables and methods in implementations and private methods so that they're self-documenting.
Way too often I see comments used as an excuse to mix application and domain logic to one hot tangled mess of code. If you separate interfaces and domain logic in separate layers the code becomes self-explanatory.
I have worked in a "clean code" aficionado environment and it's one of the points where you can clearly agree to disagree. Being able to read the code and understand what you were doing back then maybe comes with experience but if you're starting out and come back to something after a month or two, you don't know what you were doing anymore. Comments need to be maintained in the same way that code is, but there's no reason why it can't be read through during the code review as well for example.
Thank you for the information and yes these tips are very much helpful.
And I agree with the point that "we need to know which part of the code is to be commented".
In my opinion, comments should not explain what the code does. There are a few reasons to use comments though:
After these considerations, if you need to add a comment to express what the code does, then your code is crap and you should improve it instead of adding a comment.
I like this quote from Kevlin Henney: "A common fallacy is to assume authors of incomprehensible code will somehow be able to express themselves lucidly and clearly in comments."
As always, there is an exception: regular expressions.
Of course, we could write 20+ lines of code to replace a 1-line regex and make it more readable, but sometimes a regex really is the best fit for a problem. The downside is that they tend to be as legible as ancient Egyptian hieroglyphics. So those I comment what they do.
Yeah ! Well explained :)
Thanks, to be fair I wrote a few articles on clean code so I had time to practice ahaha
Hahaa greatt !! :)
Css isn't a programing language, but I find it important to comment in it, as often people will write hacky styles that aren't immediately obvious
It is a programming language, but for a very specific domain. 🙂
yes! comments in CSS should be describing which part of HTML is being styled.
shouldn't this be done by using BEM?
It can be ! Using BEM we can have good naming rules that help understand the design.
But I'm saying that if we have 6-7 classes designing header tag of HTML then we can leave a comment header and then all these classes can be kept under that ! It would be good for reference .
I don't understand the aversion for comments. I haven't yet run into a project that has too many comments. Usually they have none.
If you don't like to see the comments configure your IDE so that they're not visible. But I think eschewing them completely is unprofessional and make it harder to understand your code.
I know, I've dealt with several million line of code projects. I've never though.. oh.. shucks.. I wish this comment weren't here. Quite the opposite. I've often missed having some insight as to why you did it the way you did.
Also, you make think your programming technique is "obvious".. but 10 years from now techniques may have changed and understanding what you were thinking at the time is not that obvious. I've dealt with 30 year old code in projects.. so this isn't fiction.
In the real world code can span decades. That's what it means for a project to be successful. We don't always deal with shiny new things.
Oh yeah, the comments.
Listen, comments are useful if you explain in max one short line the block of code, thats block not line. Also you can limit commenting, by writing suggestive names for you variables and objects. So that when you read the code, the blocks you ll understant what its going on and you won't be needing large comment blocks.
Yes ! That's why I mentioned a point "Identify right places and intent to comment" . And by the way thanks for highlighting it again :)
Too many comments are useless. The code should be self-documenting.
For example in one of my projects there was a function void setupToolbar. Recently someone added a comment to it. Now the code reads:
yeah !! well said and the example is clear :)
That's why I used the statement "Don't use it everywhere"
The rule about commenting is that it's not for you. It's for who you expect to read it. If you expect your team to read it, then it would make sense to only comment confusing pieces of code, like why you would have a 3 level nested for loop (sometimes it's the only way). If however it's intended for someone who doesn't understand the code, like a webpack configuration file for example, then comments on it should be close to documentation.
Right ! Well said :)
Yes, it becomes helpful for other developers to understand easily.
Yeahh ! 😊
Skip the really obvious stuff. The question you should answer with the comment should be WHY more than WHAT.
Yeah ! That's great point !!