Billy Sclater wrote:In Robert Martin (Uncle Bob)'s book 'Clean Code'. He advises to use comments very sparingly. And seems to suggest that a comment represents that the programmer failed to code correctly in a readable fashion! So what about JavaDoc? Should this be skipped under 'clean code standards'? Does JavaDoc indicate poorly written code?
No.
Definitely not. In fact, i'd say the exact opposite.
Simply put: Javadoc is NOT "comments". It's a framework for producing API documentation; and I don't think Uncle Bob was saying that you shouldn't do that. It just happens to use a specialized comment block as a definition basis.
I suspect that UBob was referring to
Writing Dumb Code - which is something I think most of here would agree with - ie, if you have to
embed comments in your code to explain how something works, then it's probably too complicated.
That said, I'm a great believer in Einstein's quote (paraphrased): "Things should be as simple as possible,
but no simpler.".
So, if you have a piece of code that is
inherently complex, a few well-placed comments can help other people sort out the wheat from the chaff.
My 2¢.
Winston
1
