DEV Community

Is Commenting Code that necessary?

Aashritha Shiva on May 24, 2020

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. “Com...
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

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

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

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 • Edited

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

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

Hahaa greatt !! :)

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 Buinauskas

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

Collapse
 
aashrithashiva29 profile image
Aashritha Shiva

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

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

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
 
benibela profile image
Benito van der Zander • Edited

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

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

Right ! Well said :)

Collapse
 
nileshsutar4755 profile image
Nilesh Sutar

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

Collapse
 
aashrithashiva29 profile image
Aashritha Shiva

Yeahh ! 😊

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

Yeah ! That's great point !!

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

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

Collapse
 
aashrithashiva29 profile image
Aashritha Shiva

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