I think there are good reasons why Martin considers comments to be a code smell (or "failure"). One of them is that they tend to get out of sync over time and they can state falsehoods about the ever changing code base, which unnecessarily adds to confusion instead of aiding in understanding what's going on.
Comments are often neglected when code changes.
Comments are also often abused by developers by not explaining the intent, but by simply rephrasing or describing what is literally going on, or by labelling sections of more complex multi-line logic, which should be better broken out into smaller methods and modules with self-describing names, making comments ultimately redundant.
I believe the main reason why Bob Martin says that comments are a failure is that they are rarely ever necessary once all other steps have been taken into account and implemented for writing clean code. That's why the chapter about comments also comes a little later in "Clean Code", after the reader already learned a few tricks how to write code that is overall more readable and self-describing.
But Martin also lists in "Clean Code" several examples where comments are justified and needed.
For example when an external dependency, something out of your control, forces you to write a hard to follow workaround. That is a good and valid opportunity to add some explanation in plain English.
Or for clarifying something obscure, expressing the intent, or for adding some useful piece of information. So yes, he seems to agree with you. A comment should express the intent. Not only that. It can also be used to warn of consequences and to amplify a coding decision (e.g. "if we do not trim that string then component XYZ will crash").
The main takeaway from that chapter about comments, IMO, is that comments should not make up for bad code. Code that is in desperate need of refactoring. When code is so complicated and hard to read, when variable names are so nonsensical and control flow structures so nested that comments are needed for explaining what's going on there, then the code itself smells and needs to be rewritten so it can be easier understood. Better, more readable, more self-explaining code will make those comments unnecessary.
I kind of see where you are coming from that Martin's statement may come across as absolutist and condescending. But taken the entire context and the whole chapter into account, I also get what he is trying to say. And I do not read it as something along the lines of "I am better than you by never writing comments, and you are stupid for writing comments". He is also speaking of himself. He is also accusing himself of failing when he runs into a situation where he has to write a comment. We all have to use comments at some point, but running into a situation where we have to write a comment may imply most of the time that something went wrong:
Something went wrong when we have to explain messy code
Something went wrong when we have to explain a weird workaround
Something went wrong when we have to hack in a TODO comment (because we could not finish our work at the moment and we're deliberately adding technical debt to the future of the code base)
Something went wrong when we repeat the plain obvious in plain English (add 1 to x or default constructor which is obvious to any programmer)
Something went wrong when we religiously add JavaDoc to every trivial getter and setter method (set the author, get the author)
Something went wrong when we document the purpose of a variable or function name instead of giving the variable or function a better name that expresses the purpose
Something went wrong when a series of nested if statement spans over dozens of lines so we need to add // end if (x > 1) comments to the closing braces --- that code needs to be refactored instead
Something went wrong when we provide too much information (e.g. copy paste IEEE spec on top of implementation)
And so on. Still, we cannot always avoid writing comments. But I think Martin tries to strongly encourage us to avoid them and he implies that if the need arises for writing a comment, then something probably went wrong.
The book "Clean Code" is a collaboration between Martin and other authors, so it's not completely born in Martin's vacuum. Several chapters were not written by him. Martin states early on in his book that he discussed and analyzed a lot of existing (mostly Open Source) code examples with his collaborators and the best ways to improve those code snippets they selected for the book. "Clean Code" raises multiple excellent points that stem from decades of experience.
I don't think it's fair to dismiss the entire book and Martin's contributions as a whole based on a single quote you happen to disagree with. There is a lot of really solid advise and insight in it and I highly recommend it to anyone.
One of them is that they tend to get out of sync over time and they can state falsehoods about the ever changing code base, which unnecessarily adds to confusion instead of aiding in understanding what's going on.
That's a failure on the part of the programmer, not of comments. The exact same can be said of variable and function names, but we don't condemn those.
Comments are often neglected when code changes.
Only if you let them.
Comments are also often abused by developers by not explaining the intent, but by simply rephrasing or describing what is literally going on...
Yes, but even my commenting standard condemns that. Just because there is a wrong way to comment doesn't mean there is not a right way.
...that they are rarely ever necessary once all other steps have been taken into account and implemented for writing clean code.
I could bore you with an entire article series on real-world scenarios where this is not true. The rest of clean code does not preclude actual intent commenting.
The main takeaway from that chapter about comments, IMO, is that comments should not make up for bad code.
I absolutely agree. Comments have their own unique role, and fixing code ain't it.
But I think Martin tries to strongly encourage us to avoid them and he implies that if the need arises for writing a comment, then something probably went wrong.
And again, that's completely dismissing their actual use. I'm advocating for using comments in a capacity that I have never seen even the best code properly fill. And I've seen a lot of code.
"Clean Code" raises multiple excellent points that stem from decades of experience.
I'm sure it does, but even the best material wrapped in unapproachable egotism is still unapproachable egotism. I don't take issues with the content, I take issues with the author.
I don't think it's fair to dismiss the entire book and Martin's contributions as a whole based on a single quote you happen to disagree with.
Oh, I'm not. It's one example. I've read much of Robert Martin's writing, and it nearly always carries his egotism and his inability to distinguish between his opinion and objective reality.
There is a lot of really solid advise and insight in it and I highly recommend it to anyone.
There's a lot of really solid advice and insight in it....and I highly recommend anyone find a less egotistic teacher than Robert Martin to educate them; it is not wise to have to pick out the good advice from the overinflated opinions, when they are portrayed indistinguishably from each other.
Unfortunately, I've run smack into the attitude of "This Always Works, Because Uncle Bob Says" as a coding mentor and manager. It's entirely his own fault, given his predilection to "ALWAYS" and "NEVER" pronouncements, even if he makes a half-hearted attempt at qualifying them.
Just my two cents. I will never be able to respect Robert Martin, not because his ideas are all bad, but because his attitude is contemptible.
Some comments have been hidden by the post's author - find out more
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
I think there are good reasons why Martin considers comments to be a code smell (or "failure"). One of them is that they tend to get out of sync over time and they can state falsehoods about the ever changing code base, which unnecessarily adds to confusion instead of aiding in understanding what's going on.
Comments are often neglected when code changes.
Comments are also often abused by developers by not explaining the intent, but by simply rephrasing or describing what is literally going on, or by labelling sections of more complex multi-line logic, which should be better broken out into smaller methods and modules with self-describing names, making comments ultimately redundant.
I believe the main reason why Bob Martin says that comments are a failure is that they are rarely ever necessary once all other steps have been taken into account and implemented for writing clean code. That's why the chapter about comments also comes a little later in "Clean Code", after the reader already learned a few tricks how to write code that is overall more readable and self-describing.
But Martin also lists in "Clean Code" several examples where comments are justified and needed.
For example when an external dependency, something out of your control, forces you to write a hard to follow workaround. That is a good and valid opportunity to add some explanation in plain English.
Or for clarifying something obscure, expressing the intent, or for adding some useful piece of information. So yes, he seems to agree with you. A comment should express the intent. Not only that. It can also be used to warn of consequences and to amplify a coding decision (e.g. "if we do not trim that string then component XYZ will crash").
The main takeaway from that chapter about comments, IMO, is that comments should not make up for bad code. Code that is in desperate need of refactoring. When code is so complicated and hard to read, when variable names are so nonsensical and control flow structures so nested that comments are needed for explaining what's going on there, then the code itself smells and needs to be rewritten so it can be easier understood. Better, more readable, more self-explaining code will make those comments unnecessary.
I kind of see where you are coming from that Martin's statement may come across as absolutist and condescending. But taken the entire context and the whole chapter into account, I also get what he is trying to say. And I do not read it as something along the lines of "I am better than you by never writing comments, and you are stupid for writing comments". He is also speaking of himself. He is also accusing himself of failing when he runs into a situation where he has to write a comment. We all have to use comments at some point, but running into a situation where we have to write a comment may imply most of the time that something went wrong:
add 1 to xordefault constructorwhich is obvious to any programmer)set the author, get the author)// end if (x > 1)comments to the closing braces --- that code needs to be refactored insteadAnd so on. Still, we cannot always avoid writing comments. But I think Martin tries to strongly encourage us to avoid them and he implies that if the need arises for writing a comment, then something probably went wrong.
The book "Clean Code" is a collaboration between Martin and other authors, so it's not completely born in Martin's vacuum. Several chapters were not written by him. Martin states early on in his book that he discussed and analyzed a lot of existing (mostly Open Source) code examples with his collaborators and the best ways to improve those code snippets they selected for the book. "Clean Code" raises multiple excellent points that stem from decades of experience.
I don't think it's fair to dismiss the entire book and Martin's contributions as a whole based on a single quote you happen to disagree with. There is a lot of really solid advise and insight in it and I highly recommend it to anyone.
That's a failure on the part of the programmer, not of comments. The exact same can be said of variable and function names, but we don't condemn those.
Only if you let them.
Yes, but even my commenting standard condemns that. Just because there is a wrong way to comment doesn't mean there is not a right way.
I could bore you with an entire article series on real-world scenarios where this is not true. The rest of clean code does not preclude actual intent commenting.
I absolutely agree. Comments have their own unique role, and fixing code ain't it.
And again, that's completely dismissing their actual use. I'm advocating for using comments in a capacity that I have never seen even the best code properly fill. And I've seen a lot of code.
I'm sure it does, but even the best material wrapped in unapproachable egotism is still unapproachable egotism. I don't take issues with the content, I take issues with the author.
Oh, I'm not. It's one example. I've read much of Robert Martin's writing, and it nearly always carries his egotism and his inability to distinguish between his opinion and objective reality.
There's a lot of really solid advice and insight in it....and I highly recommend anyone find a less egotistic teacher than Robert Martin to educate them; it is not wise to have to pick out the good advice from the overinflated opinions, when they are portrayed indistinguishably from each other.
Unfortunately, I've run smack into the attitude of "This Always Works, Because Uncle Bob Says" as a coding mentor and manager. It's entirely his own fault, given his predilection to "ALWAYS" and "NEVER" pronouncements, even if he makes a half-hearted attempt at qualifying them.
Just my two cents. I will never be able to respect Robert Martin, not because his ideas are all bad, but because his attitude is contemptible.