aspose file tools*
The moose likes Developer Certification (SCJD/OCMJD) and the fly likes Regarding the documentation & error handling 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 "Regarding the documentation & error handling" Watch "Regarding the documentation & error handling" New topic
Author

Regarding the documentation & error handling

CyJenny Wong
Greenhorn

Joined: May 29, 2002
Posts: 18
I have some doubt regarding documentations.
(1) what's the difference between Online Help documentation vs user documentation vs ReadMe.txt
(2) Do I need to javadoc for every class variable, instance variable (either public, protected, default).
(3) How about error handling at server side, any special techniques being used.
John Smith
Ranch Hand

Joined: Oct 08, 2001
Posts: 2937

(1) what's the difference between Online Help documentation vs user documentation vs ReadMe.txt

Online help documentation and user documentation is the same thing, its just a different format that is up to you to pick. This document is a user manual.
Readme.txt is for Sun's accessor, and it should be structured precisely as specified in the instructions.

(2) Do I need to javadoc for every class variable, instance variable (either public, protected, default).

Probably not, but it would certainly not hurt if you do.

(3) How about error handling at server side, any special techniques being used.

Here is one technique, -- catch errors of various types and map them into a user-friendly messages to show in the pop up screens.
Eugene.
Kathy Sierra
Cowgirl and Author
Ranch Hand

Joined: Oct 10, 2002
Posts: 1572
Your instructions should say if your javadoc should include anything beyond public elements. But as Eugene said, it wouldn't hurt in either case.
For error handling, Eugene's tip is a good one, and I'd also include (although I know these are obvious, but they're definitely considered in the exam):
* don't hesitate to create your own exception classes if appopriate
* don't return error codes!! Ever!
* keep command-line status messages to a minimum
* be sure to always include a detail message in your exceptions, and keep the detail message as clear as possible.
cheers,
Kathy


Co-Author of <a href="http://www.amazon.com/exec/obidos/ASIN/0596007124/ref=jranch-20" target="_blank" rel="nofollow">"Head First Design Patterns"</a><br /> <br />Just a Jini girl living in a J2EE world.
Valentin Crettaz
Gold Digger
Sheriff

Joined: Aug 26, 2001
Posts: 7610
(2) Do I need to javadoc for every class variable, instance variable (either public, protected, default).
First off, I mention that I'm doing the beta exam. Even though the requirements do not mention that private or protected methods are to be javadocized, I did it because as Eugene said it doesn't hurt to do it. I just don't like it when I see an undocumented method, be it public, protected or private On small projects like the Developer assignement, that might not be a problem, but on big projects things might soon get out of hands if the documentation is not up-to-date


SCJP 5, SCJD, SCBCD, SCWCD, SCDJWS, IBM XML
[Blog] [Blogroll] [My Reviews] My Linked In
Juan Katabasis
Ranch Hand

Joined: Jun 20, 2001
Posts: 46
About error handling, i can read in 'Effective Java' (J. Blosh, Addison Wesley, 2001)
(..) It is disconcerting when a method throws an exception that has no apparent connection to
the task that it performs. This often happens when a method propagates an exception thrown
by a lower-level abstraction. Besides being disconcerting, this pollutes the API of the higher
layer with implementation details. If the implementation of the higher layer is changed in
a subsequent release, the exceptions that it throws may change as well, potentially breaking
existing client programs.
To avoid this problem, higher layers should catch lower-level exceptions and, in their
place, throw exceptions that are explainable in terms of the higher-level abstraction.
This idiom, which we call exception translation (...)

As i've read some posts from quality members talking on their assignments, and how they simply propagated the exceptions until they show them as messages, or on the bennefit of mantaining original exceptions (RemoteException as example), i still don�t see a clear criteria on what approach is better ...
[ October 15, 2002: Message edited by: Jaun Katabasis ]

Regards<br />J.
Juan Katabasis
Ranch Hand

Joined: Jun 20, 2001
Posts: 46
hi again
i'd appreciate comments on this last point: exception propagation or traduction
thanks all
Max Habibi
town drunk
( and author)
Sheriff

Joined: Jun 27, 2002
Posts: 4118
Juan,
I suggest that you propagate your exceptions forward: however, just short of displaying them to the user, I suggest that you log it, and display a friendly message. I generally suggest a GUIException and a FatalGUIException class, which are thrown by your controller.
All best,
M, author
The Sun Certified Java Developer Exam with J2SE 1.4


Java Regular Expressions
Juan Katabasis
Ranch Hand

Joined: Jun 20, 2001
Posts: 46
thanks Max for the reply
actually i am propagating my exceptions and simple messages are showed in the status bar, but i am not happy enough with this.
(in the client side) i've decided to let the status bar show optionally a jdialog with a description of the nested exceptions, so every exception can be located in its abstraction level
it's a good idea to have just two main exceptions (one for checked, other for not checked) and construct them using chaining techniques. thanks
[ October 17, 2002: Message edited by: Jaun Katabasis ]
 
I agree. Here's the link: http://aspose.com/file-tools
 
subject: Regarding the documentation & error handling