loading...

Is Commenting Code that necessary?

aashrithashiva29 profile image Aashritha Shiva ・2 min read

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)

Code

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. !

Discussion

pic
Editor guide
Collapse
etienneburdet profile image
Etienne Burdet

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.

Collapse
aashrithashiva29 profile image
Aashritha Shiva Author

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 :)

Collapse
etienneburdet profile image
Etienne Burdet

By the way I forgot, but a good README also greatly reduce the necessity for comments.

Collapse
aashrithashiva29 profile image
Aashritha Shiva Author

Yeahh .! 👍 It must clearly give the view of entire project!!

Collapse
dannyverp profile image
Danny Verpoort

"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.

Collapse
0ctavia profile image
Octa

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.

Collapse
aashrithashiva29 profile image
Aashritha Shiva Author

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".

Collapse
patferraggi profile image
Patricio Ferraggi

In my opinion, comments should not explain what the code does. There are a few reasons to use comments though:

  1. to express the developer's intent, why something was done in a certain way.
  2. to describe API functionality (if the code is gonna be used by an external project or as part of a web service)
  3. when performance is so critical that there is a reason to avoid abstractions.

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."

Collapse
ashleyjsheridan profile image
Ashley Sheridan

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.

Collapse
aashrithashiva29 profile image
Aashritha Shiva Author

Yeah ! Well explained :)

Collapse
patferraggi profile image
Patricio Ferraggi

Thanks, to be fair I wrote a few articles on clean code so I had time to practice ahaha

Thread Thread
aashrithashiva29 profile image
Aashritha Shiva Author

Hahaa greatt !! :)

Collapse
aminmansuri profile image
hidden_dude

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.

Collapse
oreoorbitz profile image
oreoorbitz

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

Collapse
buinauskas profile image
Evaldas

It is a programming language, but for a very specific domain. 🙂

Collapse
aashrithashiva29 profile image
Aashritha Shiva Author

yes! comments in CSS should be describing which part of HTML is being styled.

Collapse
patferraggi profile image
Patricio Ferraggi

shouldn't this be done by using BEM?

Thread Thread
aashrithashiva29 profile image
Aashritha Shiva Author

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 .

Collapse
rogue_halo profile image
Rogue Halo

For my courses at School it is essential to use internal commentary or else you get marks taken off. They expect you to comment nearly every line of your code project. It's kinda nailed into me now and I end up adding a lot of comments into my code, especially open source projects.

Collapse
aashrithashiva29 profile image
Aashritha Shiva Author

Yes.. this is helpful most of the time but just try to comment only on the important and toughest parts of the code. It becomes clumsy if we comment each and every line :)

Collapse
benibela profile image
Benito van der Zander

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:

/*!
 * \brief setup Toolbar
 */
void setupToolbar()
Collapse
aashrithashiva29 profile image
Aashritha Shiva Author

yeah !! well said and the example is clear :)
That's why I used the statement "Don't use it everywhere"

Collapse
kelvinmai profile image
Kelvin Mai

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.

Collapse
aashrithashiva29 profile image
Aashritha Shiva Author

Right ! Well said :)

Collapse
detzam profile image
webstuff

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.

Collapse
aashrithashiva29 profile image
Aashritha Shiva Author

Yes ! That's why I mentioned a point "Identify right places and intent to comment" . And by the way thanks for highlighting it again :)

Collapse
nileshsutar4755 profile image
Nilesh Sutar

Yes, it becomes helpful for other developers to understand easily.

Collapse
aashrithashiva29 profile image
Collapse
sebastianr1982 profile image
Sebastian Rapetti

I comment my code, first for me! it's very usefull when after some time (months or years) I come back on it! Comments help me to remember why I did things that way!

Collapse
aashrithashiva29 profile image
Aashritha Shiva Author

Yeahh ! It even helps to those who are referring your code ! :)

Collapse
leohajder profile image
Leo Hajder

Skip the really obvious stuff. The question you should answer with the comment should be WHY more than WHAT.

Collapse
aashrithashiva29 profile image
Aashritha Shiva Author

Yeah ! That's great point !!