Re: [jboss-dev] Developer javadoc is essential!

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