Win a copy of Functional Reactive Programming this week in the Other Languages forum!
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

Regarding the documentation & error handling

 
CyJenny Wong
Greenhorn
Posts: 18
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 2937
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator

(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
Rancher
Posts: 1589
5
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
 
Valentin Crettaz
Gold Digger
Sheriff
Posts: 7610
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
(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
 
Juan Ec
Ranch Hand
Posts: 46
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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 ]
 
Juan Ec
Ranch Hand
Posts: 46
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
hi again
i'd appreciate comments on this last point: exception propagation or traduction
thanks all
 
Max Habibi
town drunk
( and author)
Sheriff
Posts: 4118
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
 
Juan Ec
Ranch Hand
Posts: 46
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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 ]
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic