Win a copy of TensorFlow 2.0 in Action this week in the Artificial Intelligence and Machine Learning forum!
  • Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Liutauras Vilda
  • Paul Clapham
  • Bear Bibeault
  • Jeanne Boyarsky
Sheriffs:
  • Ron McLeod
  • Tim Cooke
  • Devaka Cooray
Saloon Keepers:
  • Tim Moores
  • Tim Holloway
  • Jj Roberts
  • Stephan van Hulst
  • Carey Brown
Bartenders:
  • salvin francis
  • Scott Selikoff
  • fred rosenberger

Is JavaDoc clean code?

 
Ranch Hand
Posts: 146
Eclipse IDE Java Linux
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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?

I'm very interested to hear your opinions!!
 
Rancher
Posts: 43016
76
  • Likes 1
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Javadocs are necessary for an API that others will use. So it's required documentation at least in that case (because users don't have the source code to figure things out). So I don't think he was talking about that case.
 
Bartender
Posts: 10777
71
Hibernate Eclipse IDE Ubuntu
  • Likes 1
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator

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
 
Everybody's invited. Except this tiny ad:
the value of filler advertising in 2020
https://coderanch.com/t/730886/filler-advertising
reply
    Bookmark Topic Watch Topic
  • New Topic