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 po...
For further actions, you may consider blocking this person and/or reporting abuse
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.
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
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.
So, you forgot one thing.
Recommend one or two you consider is Good.
But yes, I do agree with you.
Trouble is, I don't have any on hand. I've picked it up from so many places over the years. If I find some specific examples, I'll share.
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.
Least qualified, as in, he has a dangerously overfed ego. A preened ego disqualifies even the smartest person from teaching others reliably.
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.
That's a good advice, I've heard the same principle in the short form "Comment why, not how."
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.
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.)
Yeah, I couldn't agree more 😅
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).
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?
Great article. This an often overlooked but important topic.
I look forward to the follow up - “Don’t get rid of all comments”
THIS! Comments for intentions and not repeating what the code is doing
100% agree
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! :-)
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
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.
I was also arguing that Java doc in public packages, like Java official documentation is Good and needed.
Even better if some example and useage is in the documentation.
In internal methods, classes only for internal use, not so much.
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.
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
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.
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?
"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
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.
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 ✌
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!
Please mention me when you do, I'd love to read that!
Certainly!
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.
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!
hillelwayne.com/what-comments/
Great article!
That is true
oh...
jeez
strenge
Position Marker Comments are great for search purpose and visibility in minimap, but should be distinguishable from other comments.
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..
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.
Minimode placeholders should be in ASCIi art so they can be read in minimode
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 😄
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.
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.
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.
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.
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
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
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
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.
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.
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.
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.
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
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' 🙂
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!
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.
Nice article, but is the use of the term 'insane content' helpful?
That was an insane move right? 😂
Real class :(
All new engineers must read this, good article :)
I did this once in an iOS app I was making 😂
Yes, exactly what Clean Code book is stated, and totally agree.
cool
This is really about how and when to comment your code. And for that purpose, I like it.
might rewrite this with more
Great article!
Well thank you a lot!