DEV Community

loading...
Cover image for Don’t comment your code

Don’t comment your code

nadaelokaily profile image Nada Elokaily Updated on ・3 min read

Your First Developer Instinct Is To Disagree But Hear Me Out.

I'm not saying comments are all bad. If used properly comments are very powerful but they aren't the answer to your mess, in fact they might make another mess.
A code could brilliantly solve a critical problem using a well-crafted algorithm, utilizing a famous design pattern or exploiting from a revolutionary feature of a programming language, while depending on providing comments each step of the way and yet be a mystery to the team of developers maintaining it. Why?!
Some developers tend to focus more on writing time-wasting comments than on refactoring the code itself. Here are some comments your team is better off without:

Redundant Comments

Comments should be adding value or describing an original logic, not translating syntax. if the code was well written it won’t need this extra comment to narrate each line’s job.

You can clearly see here that the comment is so uncalled for especially with all the descriptive naming.

 // The processor delay for this component.
 protected int processorDelay = -1;
Enter fullscreen mode Exit fullscreen mode

Misleading Comments

The road to hell is paved with good intentions. The author can put an inaccurate comment for all the right reasons, yet that would cost a poor programmer an expensive debugging session.

For example the method here does not return when this.closed becomes true. It only returns if this.closed is true; otherwise, it waits for a blind time-out and then throws an exception if it is still not closed. The difference is astounding!

// Returns when this.closed is true. Throws an exception on timeout is reached.
public synchronized void waitForClose(final long timeoutMillis) throws Exception
{
    if(!closed){
        wait(timeoutMillis);
        if(!closed)
            throw new Exception("MockResponseSender could not be closed");
    }
}
Enter fullscreen mode Exit fullscreen mode

Mandated Comments

Some mandatory comments might not be that useful afterall. Comments should not be just clutter.

javadocs here are just clutter.

/**
 * @param title The title of the CD
 * @param author The author of the CD
 */
 public void addCD(String title, String author) {
     CD cd = new CD();
     cd.title = title;
     cd.author = author;
     cdList.add(cd);
 }
Enter fullscreen mode Exit fullscreen mode

Noise Comments

Comments should provide new information otherwise they are just noise that we learn to ignore. If you ignore a comment it means that it shouldn’t have been there in the first place.

Not only did this author write an unnecessary comment but he also forgot to add the catch body and left a mumbling comment with no context.

try
{
     // Continue normal flow
     doSomething();
}
catch(Exception e1)
{
     // Give me a break!
}
Enter fullscreen mode Exit fullscreen mode

Function or variable substitution comments

A complex code line doesn't need a comment, what it needs is to be refactored or broken to smaller components.

check this rephrasing, Amazing right?

// does the module from the global list <mod> depend on the
// subsystem we are part of?
if (smodule.getDependSubsystems().contains(subSysMod.getSubSystem())) { }
Enter fullscreen mode Exit fullscreen mode

Rephrasing

ArrayList moduleDependees = smodule.getDependSubsystems();
String ourSubSystem = subSysMod.getSubSystem();
if (moduleDependees.contains(ourSubSystem)) { }
Enter fullscreen mode Exit fullscreen mode

Position Marker Comments

Marking a particular position with a comment is rarely useful; it makes sense to gather certain functions together beneath a banner But I don't see how useful that is for each function, in general they actually may be just clutter.

Admit it you did this ;)

// Actions //////////////////////////////////
Enter fullscreen mode Exit fullscreen mode

Attribution Comments

There is no need to pollute the code with little bylines. There are so many source control tools that are very good at remembering who added what, when

Git blame is after all of us, I feel so exposed..
Alt Text

Commented-out Code

Commented out sections aren't too important to delete, Actually most source code control systems remember the code for us. We don’t need to be hoarding useless pieces of inactive code anymore.

Remember the first time you found out you're clingy?

InputStreamResponse response = new InputStreamResponse();
response.setBody(formatter.getResultStream(), formatter.getByteCount());
// InputStream resultsStream = formatter.getResultStream();
// StreamReader reader = new StreamReader(resultsStream);
// response.setContent(reader.read(formatter.getByteCount()));
Enter fullscreen mode Exit fullscreen mode

Non-local Comments

Comments should describe the code it appears near to. There should be an obvious connection between the code and the comments.

Don’t offer irrelevant or system wide information in the context of a local comment. The place for Interesting historical discussions or irrelevant descriptions of details is not comments.

Important

This article is not an invite to ditch comments. Comments are powerful tools, just use them wisely and invest in their quality, Also never forget that refactoring the code is key.

References

This article is based on Clean Code: A Handbook of Agile Software Craftsmanship by Robert C. Martin, the book is highly recommended to read, such an amazing book that will add a lot to you.

Discussion (65)

pic
Editor guide
Collapse
codemouse92 profile image
Jason C. McDonald • Edited

Mostly good article.

I agree with David, ditch the clickbait title. Your content is worthy of better than that.

Also, handle the book with tongs, hey? It's a mix of good ideas and really bad ideas, packaged so tightly together you have to already be something of an expert to parse between them. Martin is literally the least qualified person to explain Clean Coding in a healthy and constructive manner, and that's considering the fact that he coined the term. I strongly recommend sourcing your insights from someone who doesn't strut like he's the incarnation of Neo.

On the topic of comments, I like to say never send a comment to do a name's job, and never send a name to do a comment's job.

Collapse
nadaelokaily profile image
Nada Elokaily Author

I agree with you, I think it is a general rule of thumb that you shouldn't just take for granted what ever you read in a book no matter how good the book is.
These were the points that I agreed with Robert in this chapter, but no one should blindly follow them all the way.
Take whatever suits your project and makes it easier for your team

Collapse
codemouse92 profile image
Jason C. McDonald

The trouble is, you have to know what you're about before you can really "take what suits your project". There are too many young developers who read "Clean Code" on recommendation, see people quoting it like scripture, and then adopt it wholesale as the One True Way...only to walk headlong into the traps of bad practice that are intermingled with the good ideas.

One should always apply common sense, yes, but if a book is such a mixed bag that you have to heavily sift advice as a beginner to avoid taking up antipatterns...find another book. There ARE books that are generally reliable enough, and whose missteps are insignificant enough that you can rectify them with further learning without any major problems. "Clean Code" is not one of those books.

Collapse
rkennela2 profile image
Ryan Kennel 🐶

Least qualified? That is some massive hyperbole. My guess is your opinion is somewhat clouded by your Neo comment (which has some truth to it and made me laugh).

Clean code was thought provoking when it came out and helped a lot of us become better developers.

I would argue that it is now starting to show its age. Languages and IDEs have changed massively since the books release. As such, the usefulness of the book is much less than during its original release.

Collapse
codemouse92 profile image
Jason C. McDonald • Edited

Least qualified, as in, he has a dangerously overfed ego. A preened ego disqualifies even the smartest person from teaching others reliably.

Collapse
nickfotopoulos profile image
Nick Fotopoulos

You left out what you SHOULD comment. The rule is simple. Don't explain what the code does, explain what the intentions of the code are. Anyone can tell what the code is doing by looking at it, but it can often be impossible to understand why it's being done just by looking at the code alone.

Collapse
ksaaskil profile image
Kimmo Sääskilahti

That's a good advice, I've heard the same principle in the short form "Comment why, not how."

Collapse
kevinhickssw profile image
Kevin Hicks

I agree with the "comment why, not how" a lot. I'm actually a big fan of comments and push for developers to leave more, but I focus on the spots where the code can't be simplified anymore and it's still hard to read. Or the reason behind why we are doing it isn't clear.

It's easy to forget the business or technical reason why we had to do something and then not be able to find the ticket a year later explaining it.

Thread Thread
aarone4 profile image
Aaron Reese

Especially with the cadence that language and frameworks are updated today. The more efficient techniques may not have been available when the code was written. I personally have left a whole bunch of notes at the top of a Vue project explaining why I didn't use separate component files and modules (inexperienced dev team, no source code control implementation on site, no experience of setting up build pipelines etc.)

Collapse
nadaelokaily profile image
Nada Elokaily Author

Yeah, I couldn't agree more 😅

Collapse
nadaelokaily profile image
Nada Elokaily Author

I might add a new article about which comments to write but this was off the topic I wanted to discuss here,
However, the idea that comments should be adding value or describing an original logic, not translate syntax is mainly what most good comments are about, right?

Collapse
rkennela2 profile image
Ryan Kennel 🐶

Great article. This an often overlooked but important topic.

I look forward to the follow up - “Don’t get rid of all comments”

Collapse
adam_b profile image
Adam B

Absolutely. For all the modern proclamations of "self-documenting" code, code can only show what it's doing, not why. Comments are still invaluable for explaining why something is happening, and sometimes, why it hasn't been done a different way (one which might have face validity, but be wrong).

Collapse
tobiastimm profile image
Tobias Timm

THIS! Comments for intentions and not repeating what the code is doing

Collapse
joaomcteixeira profile image
Collapse
davidhmartin profile image
David Martin

I love the article, but hate the title.
Too many people read these comments-considered-harmful types of articles and mistakenly believe that all comments are bad, which is definitely not the case. In my career I've been annoyed by under-commented code more often than by over-commented.
Having said that, I pretty much agree with everything you said (apart from the title) and I found it quite well written.
The example you give under "Noise Comments" is interesting. It's a common coding standard in Java to generally avoid empty catch blocks, and, in cases where an empty catch block is justified, to include a comment in the block explaining why. If that's a real-world example, I'm guessing that the build system included a checkstyle plugin which enforced that rule, and that the "Give me a break" comment is there to circumvent it. If so, I think that developer's problems go beyond just poor commenting skills! :-)

Collapse
nadaelokaily profile image
Nada Elokaily Author

Well as they say don't judge a book by its cover 😅
If someone got through the first passage thinking that they should not be commenting their code at all they missed the point completely, we both agree that we always should try to write better code with less noise and more valuable comments to make fellow programmers' life easier in the future

Collapse
kevinhickssw profile image
Kevin Hicks

I agree that this is a great article, but also agree with David about the title. Unfortunately most people don't actually fully read an article and they will miss the point in the beginning.

I've had many devs share articles like this with me for a reason to not write comments and didn't realize the first paragraph was saying that some comments are good anyways. They only read the subheadings really.

I saw in another comment that you might write another article about which comments to write and I would highly recommend doing that.

It could also be good to include that some times some of the comments you mentioned here as bad could be good. For example mandated comments are good for public packages, APIs, build and code style / generation tools, etc.

Collapse
vitormalencar profile image
Vitor Alencar

Really nice article =)

Some times we need to comment on the code to also help some co-workers,
it happens to me so many times when I can't fully refactor some piece of code because some other part of the system ( that I usually don't have full control) would depend on it, on that cases I find it helpful to comment on the code and try to bring awareness on of the problem on the code review.

Collapse
nadaelokaily profile image
Nada Elokaily Author

Yes, you should always keep other people maintaining your code in mind, always refactor your code and write better helpful comments to help them understand the logic fast, just don't waste their time with in valuable documentation

Collapse
kaitlyn_mccormick_23b1714 profile image
Kaitlyn McCormick

I agree with Vitor. In some businesses, there are those who access the same code to determine a root cause of an issue and correct it. Sometimes, there are junior engineers who find the complex structure intimidating. I still stand by explain the why, not the how. Yet, in some cases, the complex structure if accessed by another team for the same purposes can make a big difference.

Collapse
gabrielski profile image
Gabrielski

I agree with most of your thoughts about commenting, it is indeed a pretty good article. However, I disagree with some of your ideas and I tend to believe some comments are actually helping devs, especially junior devs.

Have you considered your development progress as a junior by reading some code comments? I found they put a lot of value when the code comments are explicit about every step the method they inspect is doing, because they met this type of code through so many tutorials where they comment after each step and telling them what exactly the next line of code is doing.

For mid to senior devs, yes, the comments are not that useful except they provide some good value (like you said). But for juniors, comments might be gold lines!

Just my 2 cents ✌

Collapse
coolscratcher profile image
CoolScratcher

A lot of this doesn't apply to block-based programming like Scratch and Snap, I might write a similar article about those two crediting you for the idea. But this certainly is useful for HTML or JS. Props!

Collapse
nadaelokaily profile image
Nada Elokaily Author

Please mention me when you do, I'd love to read that!

Collapse
coolscratcher profile image
CoolScratcher

Certainly!

Collapse
nikolab profile image
Nikola Betica

Position Marker Comments are great for search purpose and visibility in minimap, but should be distinguishable from other comments.

Collapse
nadaelokaily profile image
Nada Elokaily Author • Edited

I agree, position markers can be of great help when describing a block of functions or even a chunk of code.
But for each function I think rewriting its name surrounded with some slashes doesn't really add any value, I mean what do you think of this, is it really helping the code..

// Actions //////////////////////////////////
def Actions:
...

// Decompose //////////////////////////////////
def Decompose:
...
Enter fullscreen mode Exit fullscreen mode
Collapse
darkain profile image
Vincent Milum Jr

100% agreed on this. In my codebases, position market comments along with specific white-space above is a requirement for every function, so that way the minimap is easier to comprehend, and its quicker to jump to code. The style guide I use is based around human cognitive load of the code, infinitely more important than how the computer will process the code.

Collapse
aarone4 profile image
Aaron Reese

Minimode placeholders should be in ASCIi art so they can be read in minimode

Collapse
seriousfun01 profile image
SeriousFun01

1) I don't understand this code because it has too many crappy comments that are just noise
2) I don't understand this code because it has no comments

Now which of 1) or 2) is the most likely complaint?

Collapse
nadaelokaily profile image
Nada Elokaily Author • Edited

"I don't understand this code because all the comments are crappy" is the worst which is the case that I mean in this article,
I don't mean that developers shouldn't comment their code at all, I think they shouldn't write bad comments and invest in writing better comments and increase code quality

Collapse
seriousfun01 profile image
SeriousFun01

yes, I got your point and I agree :-), but I think if you pick a random piece of code most likely you find it has no comments at all.

Collapse
stereobooster profile image
Collapse
nadaelokaily profile image
Nada Elokaily Author

Great article!

Collapse
donginging profile image
Holly.Z

That is true

Thread Thread
donginging profile image
Holly.Z

oh...

Thread Thread
donginging profile image
Holly.Z

jeez

Thread Thread
donginging profile image
Holly.Z

strenge

Collapse
eelstork profile image
Tea

I don't see this article as having a click-bait title. Once all un-wanted comments are removed, there is almost nothing left.
Only place where I leave comments is (1) where truly hard to understand code can't be replaced by something clearer; (2) marking a transitional, probably undesired code state that for production / workflow reasons can't be fixed right away.

Collapse
miguelmj profile image
MiguelMJ

Javadocs are just clutter

I can't 100% disagree with that, but after all those comments are made for automatic documentation generation. Sometimes I have found myself writing some redundant comments that, in the end, are only there so that the generated docs are complete. These are the ones I will be revisiting, not the comments themselves.
What do you think?

With the rest of points, I completely agree 😄

Collapse
aarone4 profile image
Aaron Reese

Yup. Javadocs are there to create the details of your API inputs and outputs. They are not redundant, but actually essential and must be up to date.

Collapse
estruyf profile image
Elio Struyf

Your article and a couple of other comments this week on LinkedIn and Twitter triggered me to create a VSCode extension for none believers of comments. Not saying you are a none believer, as you got valid points. Comments are an important reference for yourself and for other people.

The extension: hide comments

Collapse
rolfstreefkerk profile image
Rolf Streefkerk

this discussion should go hand in hand with refactoring and function naming because that's really what is behind a lot of what's being discussed here.
Messy code needs a lot of comments to make it obvious what it does, the opposite is also true.

Collapse
vincenthavinh profile image
Vincent Ha Vinh

It does go with functions, formatting, unit tests, etc... in the original book.

This article is kind of a dump of the comments chapter, without the whole context of the book.

Collapse
theirritainer profile image
Michael Tiel

Good article. Code should be self explanatory. There is though one thing i always allow / do myself and that is to explain things inside docblocks if it adds value for the next engineer to understand a methods body better. But the prerequisite to that is that the method must have a clear name to begin with

Collapse
garrick profile image
Garrick West

I think your argument doesn't go far enough. I'll double down on an your extreme perspective on comments: they're just a code smell. If the code is easy enough to understand, you don't need them. If you need them, then that means you're code is too complicated to stand on it's own (a dangerous situation). If you want to argue that you need "documentation" on your code, great: WRITE A UNIT TEST! Unit test when well written, can't 'lie' like comment can (e.g. get out of date - the tests will break) :) If given a choice between writing comments and writing unit tests, write unit tests!

Collapse
donnaken15 profile image
Wesley

Right on the money.

I always leave in commented out code ;(

I apparently also lost a few points in an engineering assignment for not writing enough pseudocode/comments or something, when the assignment was to make an Arduino produce music, but I only used an array, a for loop, and some constants

Collapse
justinvincent profile image
Justin Vincent

I use redundant comments because it It spaces things out and makes the code look a bit nicer. It's also easier to visually parse the full page reading form one comment to the next to get an overview of what is going on.

Collapse
abhinav1217 profile image
Abhinav Kulshreshtha

I disagree about Javadocs being clutter. IDE parse these comments to provide meaningful help and autocompletes. And when generating documentations, these comments are parsed.
Javadocs/Docblocks are and should be only proper comments in code. Take any kotlin std file, they have some really proper comments. And from personal experience, ever since I properly learnt about js-docs, both mine and people who I work with have their life simplified.
Ofcourse this doesn't mean I am against other types of comments, and I agree that if those aren't properly written, they become noise.

I think a very big issue is that there are all these amazing courses in schools, colleges and Youtube, preparing you to become a good programmer, but none put emphasizes on proper etiquette on code comments, naming standards etc. I remember when I first got a large multi-team, multi-language project, I realized how easy is it to mis-manage project because of lack of guidelines on these. There were written guidelines on how to name functions and where to put certain files, but there were nothing on supposed non-trivial stuff like commenting etiquette, and most of the issues we faced on daily basis was related to this.

Collapse
greenroommate profile image
Haris Secic • Edited

Javadoc and similar are not useless especially when writing libraries/frameworks. And main usage is from IDEs which read them and explain each param IF you explained param yourself not just put longer name. Example to your code sample: is author of the CD artist or publisher?

Aside from such, comments are highly useless in many codebases especially commented out code and explanation of the code itself as you pointed out. However simply put comment should "explain why not how". And this covers most of your points I think. In rare cases also what because WeDontNeedThisLongNamesReally

Collapse
matthewbdaly profile image
Matthew Daly

I would also add that if something can be done either as a comment, such as DocBlocks, or as a native type hint of some kind, it should always be done as the latter, and comments should only be added when they can convey additional information that cannot be conveyed purely by type hints. A type hint will be enforced by the language itself, but a comment is harder to enforce and may get out of sync, and there's little point in using comments to duplicate the type hint.

Collapse
xtofl profile image
xtofl

Thanks for this!

Since many objections raise about the title, maybe consider the positive advice: "Comment just the non-obvious". A corollary of this advice is 'make the code obvious' :).

I encountered every topic you've described in these 20+ years of coding.

  • The very worst, may be the obsolete and/or misleading comments: try out some new code by reading the comment/documentation, and find out it doesn't even compile.
  • Also recently discovered: the 10 line license preamble in each and every file: not needed at all.
Collapse
davejsaunders profile image
Dave Saunders

Good points. I wrote something similar myself recently.
dev.to/davejsaunders/my-mission-to...

I missed out commented code though, I think that's a really common one.
I do comment out code occasionally though, when I want to tell future people (or future me) 'it used to work like this, now it doesn't because of (some reason), please don't try and be helpful and change it back' 🙂

Collapse
nadaelokaily profile image
Nada Elokaily Author

Such an amazing article Dave thanks for sharing, I agree with all the points you pointed out, I also particularly like the fact that you have a greater meaning for not deleting the commented out code that no longer works, it gave me new perspective, thanks!

Collapse
karlredman profile image
Karl N. Redman

Agreed. Truth.
The bottom line is comments are*context markers* relative to the code being commented. While there is no standardization of relative context the general rule of*less is more* should be applied.

Collapse
sidchaudhary04 profile image
Siddharth Chaudhary • Edited

I did this once in an iOS app I was making 😂

// Actions //////////////////////////////////
Enter fullscreen mode Exit fullscreen mode
Collapse
derekcrosson profile image
Derek Crosson

All new engineers must read this, good article :)

Collapse
mikeralphson profile image
Mike Ralphson

Nice article, but is the use of the term 'insane content' helpful?

Collapse
nadaelokaily profile image
Nada Elokaily Author

That was an insane move right? 😂

Collapse
mikeralphson profile image
Mike Ralphson

Real class :(

Collapse
paugustinak profile image
Peter A.

Yes, exactly what Clean Code book is stated, and totally agree.

Collapse
levirs565 profile image
Levi Rizki Saputra

Great article!

Collapse
nadaelokaily profile image
Nada Elokaily Author

Well thank you a lot!

Collapse
kgilpin profile image
Kevin Gilpin

This is really about how and when to comment your code. And for that purpose, I like it.

Collapse
donginging profile image
Holly.Z

cool