This week's giveaway is in the Android forum.
We're giving away four copies of Android Security Essentials Live Lessons and have Godfrey Nolan on-line!
See this thread for details.
The moose likes Agile and Other Processes and the fly likes Javadoc Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login


Win a copy of Android Security Essentials Live Lessons this week in the Android forum!
JavaRanch » Java Forums » Engineering » Agile and Other Processes
Bookmark "Javadoc" Watch "Javadoc" New topic
Author

Javadoc

Paul Croarkin
Ranch Hand

Joined: Sep 30, 2004
Posts: 106
Do you consider code to be complete if it lacks Javadoc? I've been on projects where code reviewers will ding people for not having Javadoc. The more I code though, the more I think that most of the time writing Javadoc is just a waste of time. Of course, it is very useful for frameworks, but I think most code is written not for frameworks, but to accomplish some business need. Self-documenting method names seem to add much more value.


Thanks,<br /> <br />Paul Croarkin<br />SCEA 5, SCWCD, SCJP
Alaa Nassef
Ranch Hand

Joined: Jan 28, 2008
Posts: 460
When you are building a large enterprise system, where other systems are going to integrate with it, javadoc is really useful. It's also very useful in modular applications, where modules speak to each other. Even in simple web applications that are multi-tiered, javadoc is really important. Self-documenting method names is a necessity, but when you need to elaborate on the logic of the method, specify the defaults, the special cases, and the cases where exceptions are thrown, javadoc is the place to do that.


Visit my blog: http://jnassef.blogspot.com/
Ganesh Bhambure
Ranch Hand

Joined: Aug 19, 2008
Posts: 32
I am totally agree with Alaa .
Java doc's are as important as your coding without it your
application will be in trouble.
Ilja Preuss
author
Sheriff

Joined: Jul 11, 2001
Posts: 14112
Originally posted by Alaa Nassef:
when you need to elaborate on the logic of the method, specify the defaults, the special cases, and the cases where exceptions are thrown, javadoc is the place to do that.


I'd actually argue that well factored code and expressive unit tests are the place right place to do that. With those in place, it is my experience that in 99.9% of all cases, JavaDoc doesn't add any value.

Things are different for published APIs, of course, especially if the developers who have to program against the API won't have access to its source code. (There might still be value in giving them access to the unit tests, of course.)


The soul is dyed the color of its thoughts. Think only on those things that are in line with your principles and can bear the light of day. The content of your character is your choice. Day by day, what you do is who you become. Your integrity is your destiny - it is the light that guides your way. - Heraclitus
Alaa Nassef
Ranch Hand

Joined: Jan 28, 2008
Posts: 460
Originally posted by Ilja Preuss:


Things are different for published APIs, of course, especially if the developers who have to program against the API won't have access to its source code. (There might still be value in giving them access to the unit tests, of course.)


That was what I actually meant in my previous post. As for giving access to unit tests, I've never seen such a thing happen in the large enterprise systems I've dealt with
Jeff Langr
author
Ranch Hand

Joined: May 14, 2003
Posts: 762
Originally posted by Alaa Nassef:
As for giving access to unit tests, I've never seen such a thing happen in the large enterprise systems I've dealt with


I'll agree with Ilja that having the tests (along with well-crafted code) is far better than having Javadoc. I've seen this work well many times, and a few times in large enterprise systems. It's a lot easier to come up to speed on an API if you have well-written tests that demonstrate things working. The deficiency in Javadoc is that it doesn't enforce an explanation of how to use the method in context.

My problem with Javadoc as a standard is that most of it ends up poorly written, and rarely maintained well enough. A lot of it ends up being lies. I have no problem whatsoever with generating Javadoc. But I find that often you can remove most of the Javadoc and still get a very good generated document of the public API. Improving class, method, and param names goes a long way toward supporting this.

The things you want to avoid with Javadoc are:
  • Insisting that programmers *write* Javadoc for all functions
  • Not insisting that programmers review generated Javadoc
  • Writing Javadoc for non-public functions or non-public classes. This is absolutely a mistake.
  • Insisting that all Javadoc elements appear, e.g. (and particularly) @Param, when the default-generated Javadoc would suffice


  • Jeff
    [ September 25, 2008: Message edited by: Jeff Langr ]

    Books: Agile Java, Modern C++ Programming with TDD, Essential Java Style, Agile in a Flash. Contributor, Clean Code.
    Robert Martin
    Author
    Ranch Hand

    Joined: Jul 02, 2003
    Posts: 76
    Originally posted by Paul Croarkin:
    Do you consider code to be complete if it lacks Javadoc? I've been on projects where code reviewers will ding people for not having Javadoc. The more I code though, the more I think that most of the time writing Javadoc is just a waste of time. Of course, it is very useful for frameworks, but I think most code is written not for frameworks, but to accomplish some business need. Self-documenting method names seem to add much more value.


    I think the best code will generate meaningful javadocs without a single /**. This happens when the name of the function, and the names of the arguments are so self-explanatory that you don't need any other verbiage.

    I am not opposed to a bit of verbiage in a /** if it's really necessary; but I consider it a failure of expression rather than a good practice.

    There are very few /** comments in FitNesse, for example, and yet I consider the code to be very clean.


    ---<br />Uncle Bob.
     
    wood burning stoves
     
    subject: Javadoc
     
    Similar Threads
    Best practices for writing javadoc for a Spring-style web application?
    Other frameworks
    Are you a Javadoc Nazi
    deploy jar size, please help
    SCBCD5.0