An Interest In:
Web News this Week
- April 25, 2024
- April 24, 2024
- April 23, 2024
- April 22, 2024
- April 21, 2024
- April 20, 2024
- April 19, 2024
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;
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 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!}
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 in general they are 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 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()));
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
Dev To
An online community for sharing and discovering great ideas, having debates, and making friendsMore About this Source Visit Dev To