Meaningless Drivel is fun!*
The moose likes Developer Certification (SCJD/OCMJD) and the fly likes Document Accessors ? A matter of Style Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login
JavaRanch » Java Forums » Certification » Developer Certification (SCJD/OCMJD)
Bookmark "Document Accessors ? A matter of Style" Watch "Document Accessors ? A matter of Style" New topic
Author

Document Accessors ? A matter of Style

Uwe Schäfer
Ranch Hand

Joined: Mar 15, 2005
Posts: 52
Hi

I found myself typing stuff like this:

<code>
/**
* Gets the single, unique instance of this class
* @return the single, unique instance of this class
*/
public static final WhatEver getInstance() {
return INSTANCE;
}
</code>

or

<code>
/**
* Gets the id-Property
* @return the value of the id-Property
*/
public int getId()
return this.id;
}
</code>

The question is obvious. Is this kind of redundant commenting needed/wanted/ or (what i doubt) in any way helpful ?

Any suggestions welcome.

Oh. here is another one, that is slightly different:
<code>
/**
* Constructor just passes the Exception-Message to super-Constructor
*
* @param msg
* the Exception-Message
*/
SomeFunnyException(String msg) {
super(msg);
}
</code>
[ July 29, 2005: Message edited by: Uwe Sch�fer ]

scja|scjp|scjd|scwcd|scbcd|scdjws|scmad
Frans Janssen
Ranch Hand

Joined: Dec 29, 2004
Posts: 357
Hi Uwe,

The comment in the first two examples may seem very obvious, but I would keep it like that anyway, because it is good practice (even a must for the assignment) to have comments an all public methods.

The last example I think could be improved upon, because the comment does not really say what (specification) the method does, but rather how (design) it does that. My personal preference is to limit the javadoc method comments to pure specification and use in-line ("//") comments for remarks on design issues.

A better comment for the last one IMHO would be something along the lines of "construct a new funny exception", or just "constructor".

Frans.


SCJP 1.4, SCJD
Uwe Schäfer
Ranch Hand

Joined: Mar 15, 2005
Posts: 52
Hi Frans

thx for helpful comments. Although


A better comment for the last one IMHO would be [...] "constructor".


reads a little funny, doesn�t it ?
Frans Janssen
Ranch Hand

Joined: Dec 29, 2004
Posts: 357
Of course it reads funny! Is is a compromise between not stating the obvious and having comments for all methods

But on a serious note, I think it is an acceptable comment for trivial constructors. There is no need to write an elaborate story about those, but its courteous to provide something, so that there is no blank box in the javadoc page.

Frans.
Uwe Schäfer
Ranch Hand

Joined: Mar 15, 2005
Posts: 52
thanks.

here�s another one:

My IDE proposes somthing like this
<code>
/*
* (non-Javadoc)
*
* @see java.lang.Object#equals(java.lang.Object)
*/
public boolean equals(Object arg0) {
[...]
</code>

yes, my assignment wants me to provide javadoc for a public method.
yes, it is a public method.
but hey:
it seems absolutely reasonable not to replicate Object.equals(Object)�s contract in my implementation�s comment, right ?
Samuel Pessorrusso
Ranch Hand

Joined: Jul 21, 2005
Posts: 164
I'm using a lot of (non-Javadoc) comments, and the javadoc tool copies the super class javadoc. Is there any problem with that?
Jan Groth
Ranch Hand

Joined: Feb 03, 2004
Posts: 456
hallo uwe,

my first thought reading your post was: where did this guy get my source code from...!?

no seriously - it's good that someone mentions this problem. i think you are right, but this is not the real world, just an exam.

checkstyle has a test named "JavadocMethod", sun pays a guy sitting at his desk and checking all our submissions. i'm sure he's happy to automate some tests, one of which will be the check-for-all-comments test.

hard for us, but at long term, his job is harder ;-)

greetings from berlin,
jan.
Samuel Pessorrusso
Ranch Hand

Joined: Jul 21, 2005
Posts: 164
Do you think that there is a problem if i use (non-Javadoc) comments?
The checkstyle give me a warning, but the javadoc tool generates the javadoc documentantion for those methods.

Other thing that is in sun's java code convention is that every file has a initial comment with copyright notice, date, classname and version information. Does Anyone have done this ?

Andrew, what are you comments?

Thanks!
[ September 09, 2005: Message edited by: Samuel Pessorrusso ]
Jan Groth
Ranch Hand

Joined: Feb 03, 2004
Posts: 456
if i may ask - what is the benefit of not using javadoc in your code?

i'd say that you reduce readability, because most of the world uses javadoc. i'm using intellij-idea as an ide, and it generates javadoc on the fly, a feature i dont want to miss anymore...

i'm not andrew, but i think that if sun wants us to keep their coding conventions, they would need to write it down. but you make points if you are following any conventions, and your code is well structured and readable...

many greetings,
jan
Andrew Monkhouse
author and jackaroo
Marshal Commander

Joined: Mar 28, 2003
Posts: 11278
    
  59

Hi everyone,

First and foremost, if your instructions state "javadoc style comments must be used for each element of the public interface of each class" then you must write them in your assignment. If you do not you will fail. Simple.

Of course where you don't have anything extra to add to a comment for a class or method that you can inherit from, Javadoc has the ability to explicitly state that you are inheriting comments. I used this extensively in my project - it saved me from writing a whole lot of redundant comments, and it made it explicit to someone reading my code where the real comments would come from.

You should also note that you only have to write Javadoc for your public methods and classes. I would still write Javadoc for the other classes and methods - it looks nicer in the assignment (plus with many IDEs creating simple Javadoc there is no reason not to), however it means you do not have to agonize over getting the "perfect" Javadoc comments for non public classes and methods. So if you set appropriate accessibility on your classes (does your GUI code need access to every class in your network code, if not what access should some of your network classes be. Does your network code need access to every class in your server? If not can change the access levels of some of your server classes / methods? ...) you can avoid some of the heartaches.

Jumping away from the assignment, you might be interested in the Extreme Programming take on comments in general (basically: don't do it). Unless you are writing an API that will be used externally, few people will need the Javadoc. And if you are writing good class names / method names then the Javadoc can be redundant. If you need a lot of comments, then that might imply that your code could be rewritten to make it easier to understand (another XP mantra: refactor often). Finally, comments just get out of date (ironically, this was a reason for Javadoc: try to keep documentation with the code so that it has less chance of getting out of date :roll: ).

Regards, Andrew


The Sun Certified Java Developer Exam with J2SE 5: paper version from Amazon, PDF from Apress, Online reference: Books 24x7 Personal blog
 
I agree. Here's the link: http://aspose.com/file-tools
 
subject: Document Accessors ? A matter of Style
 
Similar Threads
ActionForward Question
Working with files in EJB
Spring Framework and Hibernate
Java app on Tomcat return "Network Error (tcp_error)" error
Transaction ManageMent in Spring with Hibernate