Don’t comment your code

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;

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");
    }
}

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);
 }

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

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())) { }

Rephrasing

ArrayList moduleDependees = smodule.getDependSubsystems();

String ourSubSystem = subSysMod.getSubSystem();

if (moduleDependees.contains(ourSubSystem)) { }

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

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

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()));

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.

Comments

[a]

might rewrite this with more

[Anders Jackson]

Well, look up Webb programming by D. Knuth. Especially with TeX and LaTeX.

Or Org-mode with Babel addition. That is litterate codeing style. Where you described your problem and add code as you go.

Best use when explaining a library or something, but also useful for programs too.

[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

[Peter A.]

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

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

[Nada Elokaily]

"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

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

[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

[Holly.Z]

cool

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

[Derek Crosson]

All new engineers must read this, good article :)