Your Web News in One Place

Help Webnuz

Referal links:

Sign up for GreenGeeks web hosting
February 20, 2021 09:04 pm GMT

Dont 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, 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 wont need this extra comment to narrate each lines 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 shouldnt 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 in general they are 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 dont 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.

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

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.


Original Link: https://dev.to/nadaelokaily/don-t-comment-your-code-5e9h

Share this article:    Share on Facebook
View Full Article

Dev To

An online community for sharing and discovering great ideas, having debates, and making friends

More About this Source Visit Dev To