• 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 Pie Elite all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Jeanne Boyarsky
  • Ron McLeod
  • Paul Clapham
  • Liutauras Vilda
Sheriffs:
  • paul wheaton
  • Rob Spoor
  • Devaka Cooray
Saloon Keepers:
  • Stephan van Hulst
  • Tim Holloway
  • Carey Brown
  • Frits Walraven
  • Tim Moores
Bartenders:
  • Mikalai Zaikin

Document Accessors ? A matter of Style

 
Ranch Hand
Posts: 52
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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 ]
 
Ranch Hand
Posts: 357
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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.
 
Uwe Schäfer
Ranch Hand
Posts: 52
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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
Posts: 357
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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
Posts: 52
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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 ?
 
Ranch Hand
Posts: 164
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
I'm using a lot of (non-Javadoc) comments, and the javadoc tool copies the super class javadoc. Is there any problem with that?
 
Ranch Hand
Posts: 456
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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
Posts: 164
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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
Posts: 456
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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
 
author and jackaroo
Posts: 12200
280
Mac IntelliJ IDE Firefox Browser Oracle C++ Java
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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
 
Don't get me started about those stupid light bulbs.
reply
    Bookmark Topic Watch Topic
  • New Topic