[jboss-dev] Developer javadoc is essential!

[Ovidiu Feodorov]

Why don't you blog about this, I'm interested in linking to your article.

Cheers,
Ovidiu

Jason T. Greene wrote:
> Hi Guys,
>
> The javadoc/code comments in our core modules are VERY lacking, so it 
> is incredibly difficult for new folks to understand how anything is 
> supposed to work (I have been hearing some groaning about this recently).
>
> All of our code, especially SPI or API classes must have javadoc which 
> explains in detail the following things:
>
> 1) How the module is supposed to be used (and how it is actually used 
> if known)
> 2) The intended behavior, and any aspect of it that is known to be 
> broken or a hack (so that someone can differentiate between a design 
> problem and just an unimplemented section that needs to be fixed)
> 3) Crticial preconditions (e.g. "this class expects that the same vfs 
> handle instance be reused during a redeploy")
> 4) Thread-access design (e.g. "this class is thread-safe and can be 
> accessed from multiple threads", "this class is not thread-safe, and 
> all callers must use a shared lock to access", "this class is intended 
> to have an instance-per-thread")
>
> If we can't answer these simple questions, then it is likely our 
> design is flawed.
>