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.

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(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/jboss-development _______________________________________________ jboss-development mailing list jboss-development(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/jboss-development