[jboss-dev] Developer javadoc is essential!

[Thomas Diesler]

(f)

Kabir Khan wrote:
> I am currently working on a "first pass" on the javadocs for the mc 
> dependency and kernel projects. As I get more familiar with the 
> internals of mc, I will keep adding to this.
> On 2 Jun 2009, at 11:42, Thomas Diesler wrote:
> 
>> 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
>> _______________________________________________
>> jboss-development mailing list
>> jboss-development at lists.jboss.org
>> https://lists.jboss.org/mailman/listinfo/jboss-development
> 
> _______________________________________________
> jboss-development mailing list
> jboss-development at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/jboss-development

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