[jboss-dev] Developer javadoc is essential!

[Thomas Diesler]

Jason,

yes, I very much agree.

This has been brought under way for MC = please monitor

https://jira.jboss.org/jira/browse/JBMICROCONT-442

To enforce "must have javadoc" I created
https://jira.jboss.org/jira/browse/JBAS-6994

Perhaps you like to ping the individual leads to create/name their 
respective JIRA issues that are supposed to improve the situation in 
their camp and have those linked to the one above.

cheers
-thomas

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.
> 

-- 
xxxxxxxxxxxxxxxxxxxxxxxxxxxx
Thomas Diesler
JBoss, a division of Red Hat

2009 Red Hat Summit and JBoss World.
Chicago. September 1-4, 2009.
http://www.redhat.com/summit
http://www.jbossworld.com
xxxxxxxxxxxxxxxxxxxxxxxxxxxx