Don’t comment your code
Tags: webdev, computerscience, codenewbie, productivity
Published: 2021-02-20 21:04:10

#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..
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/4rkh7vhkvd5nr1dpdkro.PNG)
##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.