• Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

Javadoc and coding conventions

 
Min Huang
Ranch Hand
Posts: 100
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
This is a two parter:
1) At the beginning of my source file I am to include a comment with the version number, a copyright notice, etc. How does this version number differ from the one the class's version number? (See below)

2) If a method throws only subclasses of an exception that it declares thrown, should I add @throws for each subclass? Or should I declare each subclass in the throws clause?
For example, if I have:

What should the javadoc comment be?
 
George Marinkovich
Ranch Hand
Posts: 619
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Min,
Where did you get the idea that you have to include a file header comment
(or whatever that first comment is actually called)?

I'm not saying it's wrong, I'm just curious what led you to believe you
needed it. Someone else did something like this, but I don't remeber
where he got his advice. In any case, I don't think you need to do have
this comment. It doesn't really provide much information. After all the
name of the file is not exactly a mystery to someone looking at the code,
and the version information should certainly be entered as you've done
with the @version tag. Also this "file header comment" doesn't actually
appear anywhere in the generated javadoc, does it? If it does, where does
it appear? I would be tempted to eliminate this comment unless I could
come up with some justification for including it.

Assuming there's a good reason why you can't declare the
RecordDeletedException in the throws list instead of the
RecordNotFoundException, then the issue comes down mostly to style and
convention. I would be inclined to add RecordDeletedException to the
throws list, and then comment each of the exceptions with @throws tags in
the javadoc comment. The DocCheck utility will complain if there isn't a
one-to-one relationship between the @throws tags and each exception in the
throws list.
[ April 01, 2004: Message edited by: George Marinkovich ]
 
Min Huang
Ranch Hand
Posts: 100
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Well, I got the idea from the Java Coding Conventions page from Sun:
http://java.sun.com/docs/codeconv/html/CodeConventions.doc2.html#11684
I was afraid to lose points on documentation, so I included it. They call it a beginning comment, but I am also unaware of how this comes into play with javadoc.
As for the second part, I can't include those exceptions in the throws clause because it's one of the methods in the interface that Sun gave me. I guess I'll just mention that subclasses of RNFE can be thrown in the @throws comment.
[ April 01, 2004: Message edited by: Min Huang ]
 
George Marinkovich
Ranch Hand
Posts: 619
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Min,
Thanks for the information about the beginning comment. I think you can safely omit the beginning comments from your code for the project. I didn't use beginning comments and lost no points in the documentation or general consideration sections.
Originally posted by Min Huang:
As for the second part, I can't include those exceptions in the throws clause because it's one of the methods in the interface that Sun gave me. I guess I'll just mention that subclasses of RNFE can be thrown in the @throws comment.

Have you tried including the exception subclass in the throws clause? I think that because it is a subclass of the RNFE you will not be breaking the interface contract. For example, the following compiles:
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic