[jboss-dev] Developer javadoc is essential!

[Kabir Khan]

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