This week's book giveaway is in the Servlets forum.
We're giving away four copies of Murach's Java Servlets and JSP and have Joel Murach on-line!
See this thread for details.
The moose likes Java in General and the fly likes Javadoc private state and methods. Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login


Win a copy of Murach's Java Servlets and JSP this week in the Servlets forum!
JavaRanch » Java Forums » Java » Java in General
Bookmark "Javadoc private state and methods." Watch "Javadoc private state and methods." New topic
Author

Javadoc private state and methods.

Michael Morris
Ranch Hand

Joined: Jan 30, 2002
Posts: 3451
Does anyone else do this besides me? I put javadoc comments on everything even though sometimes I wonder why. I guess I'm just obsessive compulsive that way. And what about interface method implementations and overrides? Is it necessary to doc those? I always do.
I always use meaningful names for private methods and variables so that anyone looking at the code should be able to surmize their purpose. So am I wasting my time?


Any intelligent fool can make things bigger, more complex, and more violent. It takes a touch of genius - and a lot of courage - to move in the opposite direction. - Ernst F. Schumacher
Joel McNary
Bartender

Joined: Aug 20, 2001
Posts: 1817

Don't fret; I document everything, too -- when I document. (Reminds me that it's time for another round of documentation review...)
I always use meaningful names as well. (I need those meaningful names when I get off my lazy, um, rump to document--luckily it's all my own personal code so nobody else is depending on my documentation)
[DIGRESSION]
That reminds me of my other thought when reading this article on Java 1.5:
All of these syntactic shortcuts are nice, but they seem to preclude the "self-documenting code" concept. This example in particular:

made me scratch my head the first time I read it, even though I understand all the bits and pieces involved.
[DIGRESSION DIGRESSION]
I find this code difficult to read also in part because there are no { }'s delimiting the for loop. I delimit even single line loops like this, and find it difficult to read when other people don't
[/DIGRESSION DIGRESSION]
[/DIGRESSION]
[ May 09, 2003: Message edited by: Joel McNary ]

Piscis Babelis est parvus, flavus, et hiridicus, et est probabiliter insolitissima raritas in toto mundo.
Michael Morris
Ranch Hand

Joined: Jan 30, 2002
Posts: 3451
All of these syntactic shortcuts are nice, but they seem to preclude the "self-documenting code" concept.
I don't really care for these so called enhancements. It seems to me like Collections are now being given the prominence of primitives and references. Instead of saying in the doc comment, "must be a Collection of String objects" why not check before you cast. The for enhancement seems like the best thing for me, but IMHO these things just pollute the language.
Jim Yingst
Wanderer
Sheriff

Joined: Jan 30, 2000
Posts: 18671
[Joel]: I find this code difficult to read also in part because there are no { }'s delimiting the for loop. I delimit even single line loops like this, and find it difficult to read when other people don't
Wimp. I have little objection to delimiting single-line loops, but I think that it's good practice for any Java programmer to be well-used to interpreting code in either format. Real Programmers™ like to browse Sun's source files frequently, and don't complain when braces are "missing".
Personally, I often omit braces unless I'm working under a style guide that requires them. Why take four lines for a loop (or three with that horrid-looking K&R brace style) when two will do?
[MM]: Does anyone else do this besides me? I put javadoc comments on everything even though sometimes I wonder why. I guess I'm just obsessive compulsive that way.
I feel no compulsion to put a JavaDoc comment on any private member. But if a comment seems warrented for clarity, sure, why not.
And what about interface method implementations and overrides? Is it necessary to doc those? I always do.
If the implementation has any behavior that was not already specified in the interface declaration, and that behavior is something the other programmers should know about (rather than an implementation detail that's none of their business), then yes. But otherwise I'm content to let javadoc inherit the comment from the super method.
I always use meaningful names for private methods and variables so that anyone looking at the code should be able to surmize their purpose. So am I wasting my time?
I agree strongly with this practice. I might use a meaningless name for a local variable with very limited scope - the canonical example being int i for the index of a for loop. But the moment I need to use that variable name more than
about four lines past its declaration, it gets renamed to something a little more meaningful. My variable name lengths are roughly proportional to the size of the area they're in scope.

[Joel]: All of these syntactic shortcuts are nice, but they seem to preclude the "self-documenting code" concept. This example in particular:
[deleted]
made me scratch my head the first time I read it, even though I understand all the bits and pieces involved.

Mmmm... I tend to think it's just that the new idioms aren't as familiar to everyone yet. I think the example shown was quite clear, and preferable to the old code that would be required. Moreover I think that these things help self-documenting code. Generics in particular are good for saying, in code, "the things in this List should all be Strings", or "this Map uses Strings as keys and Integers as values". Which are both things that usually would require a comment somewhere if using a plain List or Map. And autoboxing improves readability in general, taking away the distracting visual noise of casting and converting between wrappers and primitives, so we can focus instead on where the data is going, what's being done with it. This is good, IMO.
[MM]: Instead of saying in the doc comment, "must be a Collection of String objects" why not check before you cast.
Well, javadoc comments are supposed to tell a prospective user of your class everything she needs to know, without her having to look at the actual code. If I write a method that takes a Map parameter and I expect the keys to be Strings and the values to be Integers, I need to communicate that to other programmers somewho that will be visible in the javadoc. Now it's easy:
public void process(Map<String, Integer> map) {
Putting it in the declaration, I've both communicated the intent so that it will appear in javadoc, and I've also effectively put in a check to ensure that by the time my method is invoked, the type is correct. Great, less for me to worry about.
The other thing about "why not check before you cast" - well, what do you want to do if the check is false? A common practice seems to be, ignore the bad data. E.g.:

If the casts don't work, the assumption is that we shouldn't perform the operation on the bad data. Personally, I think code like this is almost always a bad idea, as it just serves to hide errors. If someone's passing keys that aren't Strings, or values that aren't Integers, the best response is probably to report it as an error ASAP. Letting a ClassCastException be trown is one good way to do that (provided you've also documented what classes are expected):

But using 1.5, this is even simpler:

Braces omitted just for Joel. There's no need for further documentation of the required classes of the key and values, or any additional code to check these things. Much more streamlined, allowing us to focus instead on the doSomethingWith() method, which is presumably where the actual work is to be done.
[ May 09, 2003: Message edited by: Jim Yingst ]

"I'm not back." - Bill Harding, Twister
Stan James
(instanceof Sidekick)
Ranch Hand

Joined: Jan 29, 2003
Posts: 8791
Back to the JavaDoc question ... I'm coming around to the view that code that requires comments to explain it is probably sick. The code should first express the author's intent. Pacakge, class, method and variable names are much more important than JavaDoc. Reduction of clutter is also critical. It makes me crazy to see 15 lines of try, catch, log around one line of business code.
I write excellent JavaDoc on packages (how to use this stuff, high level design) a little less on classes (what this represents in the archtiecture and design) but stop and look at the code real hard before I put anything on a method.


A good question is never answered. It is not a bolt to be tightened into place but a seed to be planted and to bear more seed toward the hope of greening the landscape of the idea. John Ciardi
 
Consider Paul's rocket mass heater.
 
subject: Javadoc private state and methods.
 
Similar Threads
Javadoc of private/protected methods/variables
javadoc
NX: Default Class Visibility
Documentation Comments (scjd)
JavaDoc private fields and methods