Java EE author Adam Bien has some provocative remarks in an interview on java.sun.com. Bien says about Java EE:

Distribution of data and concurrency are the hardest challenges. Many of the best practices and patterns address these problems. The best advice I know is: 'Don't distribute.' Therefore, a fat client with a local, embedded database, such as Java DB, is the simplest possible solution -- everything else is a workaround. You are already in trouble if another client would like to access your data because then you will have to access the database remotely. But with a local embedded database your data is shared and distributed. Objects with the same identity live in the database and in the clients. If you move your business logic from one client to another tier, you will already get the Java EE 5 complexity.

Does anyone else take issue with his "don't distribute" mantra? It may be the simplest solution, but that doesn't make it the most efficient or desirable. To his credit, he points out something I've often felt about javadoc:

Most of the Javadoc comments in projects are worthless. They redundantly describe information that can be easily obtained from the method's signature. Developers are actually forced by, for example, QA (Quality Assurance), to write dumb Javadoc, just to increase some metrics. However, this approach is expensive, first, because the creation of superfluous documentation takes a huge amount of time. Second, redundant Javadoc (e.g., repetition of the parameters and return values in Javadoc) is hard to maintain. And third, what’s worse, in the maintenance phase all developers are forced to filter out relevant things and ignore worthless information.

Writing Javadoc often feels like an exercise in the absurd, and a waste of time. Am I alone in this? [Editor's note: no, you're not alone. But what's the point here? Poor documentation is a lack of effort, not a fault of javadoc itself; someone who quotes the program code in javadoc is doing themselves and their antecedents a disservice. Personally, I'd hoped that the OpenJDK would yield hordes of people fixing javadocs so that the runtime was useful. I sure wish JDocs had been a Sun initiative... and good on DZone for doing it instead.]

Most of the Javadoc comments in projects are worthless. They redundantly describe information that can be easily obtained from the method's signature.

I couldn't agree more. And this is the fault of JavaDoc, or more precisely tools that generate JavaDoc, because of the brain-dead, redundant JavaDoc skeleton comments that so many JavaDoc tools generate. The best code documentation policy I've seen was where developers leave almost all comments out of the code and write a seperate .doc with the comments for each file. The only documentation in the code is in cases where the code is not clear, and that was rare in that particular company because your code would flunk code review except in the rare case where it was needed. Having seperate .doc files with the comments helps tech. writers develop the user manuals. It also seems to encourage developers to write meaningful comments instead of the redundant crap that tools like Eclipse generates. I strip the meaningless, redundant JavaDoc comments out of code because they make it harder to read the code itself.

I get really sick of APIs with either NO javadoc, or useless javadoc. What is so controversial about describing what a class is for, what its methods do, and how the parameters effect the return value? I agree that empty javadoc comments are stupid (thank you all Java IDEs everywhere), but javadoc is a great technology; something that I believe helped Java reach the heights it's at today. Because some manager doesn't understand what "document your code" means or because Eclipse puts lame defaults in doesn't mean javadoc is bad technology or useless. Good javadoc: java.util Bad javadoc: Hibernate

I get really sick of APIs with either NO javadoc, or useless javadoc. What is so controversial about describing what a class is for, what its methods do, and how the parameters effect the return value? I agree that empty javadoc comments are stupid (thank you all Java IDEs everywhere), but javadoc is a great technology; something that I believe helped Java reach the heights it's at today.

Because some manager doesn't understand what "document your code" means or because Eclipse puts lame defaults in doesn't mean javadoc is bad technology or useless.


Good javadoc: java.util
Bad javadoc: Hibernate

He didn't say JAVADOC is useless, he said most of the javadoc CONTENT is useless.

I get really sick of APIs with either NO javadoc, or useless javadoc. What is so controversial about describing what a class is for, what its methods do, and how the parameters effect the return value? I agree that empty javadoc comments are stupid (thank you all Java IDEs everywhere), but javadoc is a great technology; something that I believe helped Java reach the heights it's at today.

Because some manager doesn't understand what "document your code" means or because Eclipse puts lame defaults in doesn't mean javadoc is bad technology or useless.


Good javadoc: java.util
Bad javadoc: Hibernate

This is, what I wanted to emphasize in the interview. We should document the intention and not the obvious stuff.

The best code documentation policy I've seen was where developers leave almost all comments out of the code and write a seperate .doc with the comments for each file.

Could not disagree more. If it works for you that is fine, but I usually feel best place to document is in the source file itself. Agreed eclipse and other tools generate too much of obvious javadoc template, much of that can be ignored or stripped or be configured not to generate in the first place. Speaking about code reviews and other tools, all of them can be configured to be not too anal about little things. Along with javadoc which is for developers, I usually recommend a minimal webpage (or any other form of document) that describes that the software is doing and how to use it etc.

Along with javadoc which is for developers, I usually recommend a minimal webpage (or any other form of document) that describes that the software is doing and how to use it etc.

Internal Developer WIKI did wonders for our team in this case.

To say JavaDocs are generally worthless is definitely a sweeping generalization. Javadocs are probably used less with the advent of auto-completion in IDEs, but I think if JavaDocs disappeared altogether, there would be an outcry in the community. In my experience, high level component documentation is probably best externalized in a separate document, but when you are doing actual integration and you want more information on each class, JavaDocs are great. If JavaDoc comments are lacking, you can go one step further if you use JSourcery's [http://jsourcery.com] software [http://www.jsourcery.com/webstart/1.5/launch15.jnlp]. You can generate links to the Java source code from your Javadocs. You can see an example here [http://jsourcery.com/api/apache/jakarta/commons/fileupload/1.1.1/index.html]. Note, that you can trace program execution once in the source code. Rob

Most of JavaDocs comments in Projects are worthless due to valid reasons mentioned by author. Adding @Obvious tag probably would be the greatest improvement for JavaDocs. However adding a seperate .doc file for comments is most anti-developer approach I have ever seen. Usually started in projects by a manager who has no idea on development practices. There is no way to guarantee synchronization between .doc and .java file and will never be maintained on the longer term (usually ends with the manager who enforced the policy leaving the group). Inspite of its drawbacks, JavaDoc was an innovative idea when Java was first introduced. Today we are in dire need of next gen JavaDoc.

Most of JavaDocs comments in Projects are worthless due to valid reasons mentioned by author. Adding @Obvious tag probably would be the greatest improvement for JavaDocs.

However adding a seperate .doc file for comments is most anti-developer approach I have ever seen. Usually started in projects by a manager who has no idea on development practices. There is no way to guarantee synchronization between .doc and .java file and will never be maintained on the longer term (usually ends with the manager who enforced the policy leaving the group).

Inspite of its drawbacks, JavaDoc was an innovative idea when Java was first introduced. Today we are in dire need of next gen JavaDoc.

I agree with this. People adding redudant/obvious info is not a JavaDoc problem. JavaDoc is a tool. Reviews will help to enforce best practices. Keeping documentation in sync with code is a huge problem. It's too easy for developers to change the code and leave in some in-line comments which hang around to mislead and confuse future developers. But I don't think anything but careful review and enforcement of best practices can help this.

Once you get past the problem of redundant/worthless JavaDocs (no simple thing to do) you still have the problem of JavaDoc cluttering up your code. Well designed and written code needs few comments. The JavaDoc is normally for the users of your APIs, not for the maintanence team. Having lots of comments in you code clutters it up for the maintanence team. It's no more difficult to keep external docs up to date then it is to keep JavaDoc up to date.

Writing Javadoc often feels like an exercise in the absurd, and a waste of time. Am I alone in this?

No, you are not. There are probably ~70% of IT professionals that fall into the same category of sub-par amateurs that frankly don’t know what they are doing or why. Being a top-notch developer is a lot, lot more than most of us realize or will ever achieve. In my team, Javadoc is a code and gets thoroughly code-reviewed regularly. Anybody who would voice the above sentiment seriously would be fired the same day (never happened) as it is clear indication of sheer lack of understanding what software engineering is (remember: get the wrong people off the bus as soon as possible). Look at our Javadoc http://www.gridgain.com/javadoc/index.html It doesn’t take much time to produce or maintain it once the team got in the groove. We also maintain wiki for more general information. I don’t require full javadoc for privates, but for most public and protected I require full Javadoc. Anyways, this topic is endless and I just voiced my personal opinion. There are plenty of people in this industry that go for a shock value of the comments with little or no substance behind them. And they usually get the most of the publicity because TSS needs clicks. Best, Nikita Ivanov. GridGain - Grid Computing Made Simple

In my team, Javadoc is a code and gets thoroughly code-reviewed regularly. Anybody who would voice the above sentiment seriously would be fired the same day (never happened) as it is clear indication of sheer lack of understanding what software engineering is (remember: get the wrong people off the bus as soon as possible).

Look at our Javadoc http://www.gridgain.com/javadoc/index.html It doesn’t take much time to produce or maintain it once the team got in the groove. We also maintain wiki for more general information. I don’t require full javadoc for privates, but for most public and protected I require full Javadoc.

Best,
Nikita Ivanov.
GridGain - Grid Computing Made Simple

I took a quick look at the javadoc for eg. GridAdaptiveLoadBalancingSpi. This is just like javadoc should be. Do you generate the diagrams automatically? How is your javadoc creation and validation workflow process set up? Which custom annotations have you created, and why. Do you have some javadoc-howto manual for your new developers? I work in a 'the-code-explains-itselves' environment, but i personally prefer well-written javadoc for certain points where you expose the api to other projects, etc. Unfortunately, I can't convince my co-workers about the importance of well written javadoc.

Hi David, That was my point that there’s really not much to do to have a normal Javadoc. We use yDoc for diagram generation, we provide custom CSS and use normal Ant Javadoc (with all its customizations). We provide proper package.html for every package and most importantly we care about the content of the Javadoc. And finally all that is package into one Ant task – so that we are always one-click away from seeing our Javadoc in a production mode. That’s all. Nikita Ivanov. GridGain – Grid Computing Made Simple

Let's get some simple things out of the way (some of which are tangential to Adam's thesis I admit, but related none the less): 1. Anyone who thinks commenting in general is useless is themselves useless and will never be a member of my staff for sure. 2. Anyone that thinks that the job of comments is to make up for poorly-written code is a moron who will never be a member of my staff for sure. 3. Anyone who says that "code should be self-documenting" and commenting is therefore redundant either (a) does not understand the point of commenting or (b) believes that their code is perfect, which guaranteed it's not. The point here being simply this: if you take the argument about commenting to *either* extreme, as seems to be the case with too many people, you're doing someone a disservice, quite possibly yourself. Commenting should enhance the readability of code and is, say it with me, *NOT* an optional component of coding. You can write the clearest code you can possibly imagine and that won't change the fact that: * Someone coming to the code fresh will probably be able to understand the mechanics of the code well enough but may not be able to see the bigger picture. * THE CODE IS NEVER AS CLEAR AS YOU BELIEVE IT IS. If you can understand the code without the comments, you're doing a good job. If you can get the general gist of the code by reading just the comments, you're also doing a good job. If combined they give you a clear, accurate, complete picture of the whole system, you're doing a spot-on job. Why developers as a whole don't seem to underatand there is a synergy there is something I don't understand. Why so many feel it has to be one or the other is just beyond me. I think that Adam makes a fair point: it's easy to write redundant, pointless comments, and many people do that. We've also seen it, it's not unusual. That is in no way the fault of javadoc, nor is it a fault of the concept of writing comments in general. It's the fault of poor coders who don't get it. Coders who believe they are better than they actually are, coders who don't take maintenance into consideration, coders who are either too stupid or just don't care enough to do the job right. They won't be working for me, and if we're all lucky they won't be working for anyone anywhere that doesn't involve a deep-fryer and a drive-up window.

Let's get some simple things out of the way (some of which are tangential to Adam's thesis I admit, but related none the less):

1. Anyone who thinks commenting in general is useless is themselves useless and will never be a member of my staff for sure.

2. Anyone that thinks that the job of comments is to make up for poorly-written code is a moron who will never be a member of my staff for sure.

3. Anyone who says that "code should be self-documenting" and commenting is therefore redundant either (a) does not understand the point of commenting or (b) believes that their code is perfect, which guaranteed it's not.

The point here being simply this: if you take the argument about commenting to *either* extreme, as seems to be the case with too many people, you're doing someone a disservice, quite possibly yourself. Commenting should enhance the readability of code and is, say it with me, *NOT* an optional component of coding. You can write the clearest code you can possibly imagine and that won't change the fact that:

* Someone coming to the code fresh will probably be able to understand the mechanics of the code well enough but may not be able to see the bigger picture.

It is not JavaDoc of the single class/interface that could give you the bigger picture. It's the documentation of used patterns/models/architectures that helps you to master the code. IMHO JavaDoc is useful for the API of interfaces, rarely for classes.

* THE CODE IS NEVER AS CLEAR AS YOU BELIEVE IT IS.

In this case, I don't think that JavaDoc comment would help.

If you can understand the code without the comments, you're doing a good job.

When I read the code I rarely check the docs. I always try to figure out what I'd do in the same situation and this drives me in the investigation. I have a rather high success ratio in understanding code, etiher well written or bad written.

If you can get the general gist of the code by reading just the comments, you're also doing a good job. If combined they give you a clear, accurate, complete picture of the whole system, you're doing a spot-on job. Why developers as a whole don't seem to underatand there is a synergy there is something I don't understand. Why so many feel it has to be one or the other is just beyond me.

I think that Adam makes a fair point: it's easy to write redundant, pointless comments, and many people do that. We've also seen it, it's not unusual. That is in no way the fault of javadoc, nor is it a fault of the concept of writing comments in general.

As I pointed out, several aspects of a system are not well documentable with JavaDoc.

It's the fault of poor coders who don't get it. Coders who believe they are better than they actually are, coders who don't take maintenance into consideration,

I would add poor QA people too to the list. Anyway, is not good JavaDoc that would increase maintainability of a system. You could always write wonderful javadoc for very stupid classes and you will go into troubles when it's time to change something.

coders who are either too stupid or just don't care enough to do the job right. They won't be working for me, and if we're all lucky they won't be working for anyone anywhere that doesn't involve a deep-fryer and a drive-up window.

Guido

It is not JavaDoc of the single class/interface that could give you the bigger picture.
It's the documentation of used patterns/models/architectures that helps you to master the code.
IMHO JavaDoc is useful for the API of interfaces, rarely for classes.

I was really talking about the bigger picture in terms of what the class/method/block of code inside a method is for. You're right to say it won't give you the "big picture" on it's own in terms of the entire system, at least, one class taken isolation isn't likely to. But if the comments are well-written at the class level it *should* help you understand where that class fits into the bigger picture, which is very valuable, so in a sense it can help give you the bigger picture, but certainly it isn't likely to do it on it's own.

* THE CODE IS NEVER AS CLEAR AS YOU BELIEVE IT IS.

In this case, I don't think that JavaDoc comment would help.

I think it can if the comments are well-written. My point is that trying to understand code can be difficult, but if you have well-written comments then at least you can say "ok, I know what the code is supposed to do, so now I can try and parse it and get the details from it". I can only speak for me, but I know that looking at other peoples' code gives me a headache, and in fact, looking at my own code some time later does too, not because either is poorly-written but just because I find it taxing to get the gist of what's going on from just the code. I know that's a bit unusual for a developer, and it's not that I can't do it, in fact I do it all the time, but I find my life is considerably easier and my brain hurts less when there's comments that say "this code does X, Y and Z for reasons A, B and C", and then the code makes a whole lot more sense as I'm mentally parsing it.

If you can understand the code without the comments, you're doing a good job.
When I read the code I rarely check the docs.
I always try to figure out what I'd do in the same situation and this drives me in the investigation.
I have a rather high success ratio in understanding code, etiher well written or bad written.

But how do you "figure out what you'd do in that same situation" if you aren't sure what's *supposed* to be happening? I come at things just the opposite: the comments tell me what's going on, then the code fills in the details of the process. For me, if you can't put into plain English what the code is supposed to do, it's probably not good code. Now, this does assume the comments are kept current and and are meaningful in the first place, neither of which is a given in my experience (and I suspect yours), but assuming both those things are true, I think the comments enhance the code considerably.

As I pointed out, several aspects of a system are not well documentable with JavaDoc.

I think that's a fair point. I've seen (and have written) javadoc that went far and beyond what Javadoc typically does... just check out the javadoc for Apache Commons Digester... there's probably more there than should be, in terms of what javadoc was meant for, but it's useful none the less, so javadoc *can* I think comment those "undocumentable" aspects of a system... but I don't disagree if you say it's not the best tool for the job.

I would add poor QA people too to the list.
Anyway, is not good JavaDoc that would increase maintainability of a system.
You could always write wonderful javadoc for very stupid classes and you will go into troubles when it's time to change something.

Hehe, if you're lucky enough to have QA folks checking your javadoc then I applaude your organization! :) Are you saying that good javadoc *can't* increase the maintainability of a aystem? I would strongly disagree with that statement. I think *any* GOOD documentation enhances maintainability. If you're instead saying that javadoc isn't the be-all and end-all of documentation, that I would certainly agree with. I also don't like the argument, which I've heard plenty of times over the years, that commenting code isn't a good idea because the comments never keep up with the code and therefore are more harm then good. I'm not at all disagreeing with that fact that it's a real problem, I've seen it many times, and it's a hassle. But that's nothing but laziness IMO. Yes, it's more work to keep the comments and code in sync, but I view it as a very worthwild exercise that gives a substantial return on the time investment to do it. Thanks Guido, Frank

It is not JavaDoc of the single class/interface that could give you the bigger picture.
It's the documentation of used patterns/models/architectures that helps you to master the code.
IMHO JavaDoc is useful for the API of interfaces, rarely for classes.

I was really talking about the bigger picture in terms of what the class/method/block of code inside a method is for. You're right to say it won't give you the "big picture" on it's own in terms of the entire system, at least, one class taken isolation isn't likely to. But if the comments are well-written at the class level it *should* help you understand where that class fits into the bigger picture, which is very valuable, so in a sense it can help give you the bigger picture, but certainly it isn't likely to do it on it's own.

* THE CODE IS NEVER AS CLEAR AS YOU BELIEVE IT IS.

In this case, I don't think that JavaDoc comment would help.

I think it can if the comments are well-written. My point is that trying to understand code can be difficult, but if you have well-written comments then at least you can say "ok, I know what the code is supposed to do, so now I can try and parse it and get the details from it".

I can only speak for me, but I know that looking at other peoples' code gives me a headache, and in fact, looking at my own code some time later does too, not because either is poorly-written but just because I find it taxing to get the gist of what's going on from just the code. I know that's a bit unusual for a developer, and it's not that I can't do it, in fact I do it all the time, but I find my life is considerably easier and my brain hurts less when there's comments that say "this code does X, Y and Z for reasons A, B and C", and then the code makes a whole lot more sense as I'm mentally parsing it.

If you can understand the code without the comments, you're doing a good job.
When I read the code I rarely check the docs.
I always try to figure out what I'd do in the same situation and this drives me in the investigation.
I have a rather high success ratio in understanding code, etiher well written or bad written.

But how do you "figure out what you'd do in that same situation" if you aren't sure what's *supposed* to be happening? I come at things just the opposite: the comments tell me what's going on, then the code fills in the details of the process.

Maybe it might sound strange, but I try figure out things by the name of the method/class/package. It is a way to understand the approach the programmer had; what you can expect to find. The first serious book I read about OOA/OOD was Rumbaugh OMT and he wrote that names identification was one of the most important things during analysis/design. I could not agree more. When someone shows me an object model I always say "tell me about this class". If the guy can't answer **what** that class is without telling what **it does** then I begin to think that the model is not as good as it could seem. Classes are things and do something because they are exactly **that** things. You can apply the same principles to methods, members, packages.

For me, if you can't put into plain English what the code is supposed to do, it's probably not good code. Now, this does assume the comments are kept current and and are meaningful in the first place, neither of which is a given in my experience (and I suspect yours), but assuming both those things are true, I think the comments enhance the code considerably.

Oh yes.

As I pointed out, several aspects of a system are not well documentable with JavaDoc.

I think that's a fair point. I've seen (and have written) javadoc that went far and beyond what Javadoc typically does... just check out the javadoc for Apache Commons Digester... there's probably more there than should be, in terms of what javadoc was meant for, but it's useful none the less, so javadoc *can* I think comment those "undocumentable" aspects of a system... but I don't disagree if you say it's not the best tool for the job.

I would add poor QA people too to the list.
Anyway, is not good JavaDoc that would increase maintainability of a system.
You could always write wonderful javadoc for very stupid classes and you will go into troubles when it's time to change something.

Hehe, if you're lucky enough to have QA folks checking your javadoc then I applaude your organization! :)

No, at all. But I worked for a customer who wanted every method with javadoc. Even beans setter/getter. Maybe because his QA had some tool to check if any class had no javadoc, I don't know/remember. Has comment ? -> OK Has no comment ? NOK

Are you saying that good javadoc *can't* increase the maintainability of a aystem? I would strongly disagree with that statement. I think *any* GOOD documentation enhances maintainability.

I get your point, but I fear that it is pureley theoretical. I would be very surprised to find bad code with GOOD documentation :-)

If you're instead saying that javadoc isn't the be-all and end-all of documentation, that I would certainly agree with.

I also don't like the argument, which I've heard plenty of times over the years, that commenting code isn't a good idea because the comments never keep up with the code and therefore are more harm then good. I'm not at all disagreeing with that fact that it's a real problem, I've seen it many times, and it's a hassle. But that's nothing but laziness IMO. Yes, it's more work to keep the comments and code in sync, but I view it as a very worthwild exercise that gives a substantial return on the time investment to do it.

Thanks Guido,
Frank

Guido

I disagree with you. Comments in code is an old practice from the world of structure programming in languages like COBOL , any programmer worth his salt would understand a decently well written Java code. I one for sure do not want to work for disgruntled and innovation killing bosses who insist on code review and commenting, it is not worth the time and effort to have another developer review the code written by a peer.

any programmer worth his salt would understand a decently well written Java code

Any programmer worth his/her salt can understand any code given the time to do it. What we're talking about here is about whether decent Javadocs add to the speed at which a programmer understands things, and the obvious answer to that is yes. In the open source world you have two groups for your system. Firstly fellow programmers on that project. In general they will understand the code already anyway so Javadocs are only useful in giving them a quick overview of new classes. Secondly users who are interested in getting involved. They are the ones who are starting from scratch and so they need this information

any programmer worth his salt would understand a decently well written Java code

I wonder if we as a community understand how narrow minded statements like this are? The purpose of javadoc is to communicate, and like all forms of communication the more you put into it, the richer the understanding. if the communication is trivial than it is obvious, but that is rare. I guess it's your prospective? If you work in an environment, where everything fits the mode, and nothing is out of the ordinary, than I would almost say do your project in a language/platform that is simpler than JEE. We and many companies push the JEE and Java, and take full advantage of the technical capabilities, and patterns to build Extremely complex Business Solutions, or handle tons of data, or some aspect that breaks the "Easy Mode" and "everything is Obvious mode". Good javadoc is great for the current project, and the people who work on the project once the development has passed to the next team or project manager. It's not perfect, but it's what we have that is standard. If enough of us don't like it, guess what?? We will build something different... Until than, I find no excuse for not documenting your code. It should not be factored in as an option for delivering code. Delivery = Documentation. Architect and Project managers should try to switch Developer roles of their developers a few times in the middle of a project, to see the reaction of the project once it has been passed off to a support team.

any programmer worth his salt would understand a decently well written Java code

I am a Sun Certified Programmer, Certified web Components Developer, Certified Business Objects Developer, and Certified Architect (1 or 3), and still I am shocked with the code that developers come up with. SHOCKED! Does it work, yep.. can I easily follow it??? NOPE! Do I have the time to do this 3-10 times a day? Absolutely not! Trust me, when I am called into a project, it's because something is broken, and it's never anything that is easy. Without Javadoc, or something, I am starting from scratch, which is unacceptable. Tony McClay Sun Certified Java Programmer (SCJP) Sun Certified Web Component Developer (SCWCD) Sun Certified Business Component Developer (SCBCD) Sun Certified Enterprise Architect (SCEA) (1 of 3)

I have seen comments describing a method embedded in Javadoc that exceed the number of lines of actual code. Is this helpful if so, in which way? I would rather go thru the actual code and understand it than reading the comments in plain english describing the method. I think UML articrafts are much more beneficial than Javadoc. These two are not mutually exclusive though. Javadoc lists all the classes,packages,methods , it does not tell you the story about navigation of methods like a sequence diagram. I can take the entire code base reverse engineer it and generate all the UML articrafts I need.

Here are the rules I use to guide how I use Javadoc: 1) Always put a javadoc comment on each class or interface. The purpose of this is to define this class's place in the application or package as a whole. Occasionally, as when the class is designed to be used in a Spring XML application context, I would add an example of how to configure it there. 2) Sometimes add a javadoc comment to a public method (or occasionally a public instance variable) if you can see someone hovering over the use of the method in an IDE and being able to make use of it. (Side note: If renaming the method or its arguments will remove the need for the javadoc, consider renaming it.) Defining what causes exceptions (even non-checked ones) is something that is ocassionally useful. 3) Never put a javadoc on any getter or setter unless RULE 2 requires it. Usually, a call to these methods is self-explanitory. In some IDE's, hovering over a property name when entering a Spring bean's XML will show javadoc. That might make it useful to enter some javadoc on the setter only. 4) Know the rules of javadoc and leave out anything that causes HTML javadoc or IDE generated hover-popups to hold duplicate information. (eg. "@param i int - index desired" generates "int" twice.) (eg2. Putting the method name in the text of the javadoc is redundant as well.) Always think about how the resulting javadoc will look and seldom how it looks in the source code. -- Lee

Failing to write some meaningful documentation is nothing but laziness (or lack of time of course). The method signature hardly ever defines what a class or method really should do, in particular it does not describe side effects, preconditions on the data, error cases, polymorphic behavior (well, we have Java6 of course, but what types are in the List of List getObjects might just be interesting). Of course it sometimes feels a bit odd to write redundant information on getters and setters but even there JavaDoc is often quicker to navigate than a modern IDE.

With about the same justification, one could easily argue (and some do!) that generalization is futile. When generalizing a piece of code, say into a function, a code, a template etc. you are limiting your options in how the pieces of code that originally were generalize evolve independently. Of course clever people would say: Hey but you are generalizing the intention and the meaning of the code. Probably your abstraction was wrong in the first place. Quite right. But intentions change. Look at a (still incomplete) generalization of date and time handling and formatting in the Java Programming language. That was a lot of work to do more or less properly. So one could say: In any real world business driven software project, generalization is an overhead that can not be paid. But then again, this should not be generalized.... Tune in next time, when you want to hear Dr Bob say: "Control structures suck, all you need is jump labels"

Interesting discussion. I posted recently some clarifications on JavaDoc to clarify some "provocations" :-) http://www.adam-bien.com/roller/abien/entry/huge_discussion_about_javadoc_and