5 Replies Latest reply on Jun 24, 2010 11:03 PM by Thomas Diesler

    The Importance of JavaDocs

    Andrew Rubinger Master

      Hey guys:


      So in the process of building the EmbeddedAS container I've come across a bunch of undocumented code which leads me to question marks.   Do we yet have a page for coding standards, some guideline we should aim to meet?  If not, we could even share one with ShrinkWrap, or under the "JBoss Testing" umbrella.


      As the team grows I expect we'll all have a tougher time navigating each other's thoughts, so let's make an effort to doc as we go along.  We're a testing group and thus must become the beacon for clean code and standards to all.



        • 1. Re: The Importance of JavaDocs
          Dan Allen Master

          We've got a substantial list going for Seam 3:


          Guidelines for Seam 3 development


          While working on these, I couldn't help but to think that perhaps we should have some foundation guidelines at JBoss Community. That way, each project can say "we extend those guidelines in the follow ways" rather than having to start over every time. It would also make my IDE setup simpler since I wouldn't have to keep importing formatting profiles for every project.


          So while I agree JBoss Testing would be a good umbrella, maybe we need to go higher. Perhaps even version them, so we say "JBoss Development Guidelines 1.0".

          • 2. Re: The Importance of JavaDocs
            Andrew Rubinger Master

            The only thing that concerns me about going any higher than "JBoss Testing" is that it'll become increasingly difficult to get concensus about what constitutes "good form" from the variety of personalities throughout the .org community.  In many senses it's a great thing that each project gets to govern its own land.


            For instance in EJB3 we set steadfast rules regarding backwards compatibility and componentization that would infuriate the lot here.   But because we have different requirements, they become necessary in that arena.




            • 3. Re: The Importance of JavaDocs
              Dan Allen Master

              Got it. That does make sense because I know these things can become ideology wars. I can only imagine what a response might be on thecore. That's why I'm suggesting "profiles". We can create these profiles but share them for central reference. On the one hand, we could have a "JBoss Testing" profile, but I think that makes projects which don't consider themselves testing hesitant to adopt them.


              So perhaps was can just use an arbitrary name, like from the military alphabet: "alpha" "bravo" or whatever. I just think that makes more sense then saying "Weld" or "Seam" profile since it is really something people just latch on to. It's a common set of conventions that we all share.


              I suggest: Tango


              And we should version it, so that we can track when it changes (so people know to check it out again).


              Unless you think I'm completely insane, I'll create a Tango 1.0 development guidelines page and say "we follow that".

              • 4. Re: The Importance of JavaDocs
                Dan Allen Master

                Projects like Seam and Weld can of course extend it for specific things, like how to define interceptors or something. But at least those are only the parts that differ from Tango, rather than restating it all from scratch.

                • 5. Re: The Importance of JavaDocs
                  Thomas Diesler Master

                  Jason says


                  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 behaviour, 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) Critical 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")