Subversion Repositories HomeAutomation

Rev

Rev 1398 | Blame | Compare with Previous | Last modification | View Log | SVN | RSS feed

  1. <html>
  2.  
  3. <head>
  4.     <title>JavaDoc guidelines</title>
  5.     <link rel="StyleSheet" href="doc.style.css" type="Text/CSS">
  6. </head>
  7.  
  8. <body>
  9.  
  10.     <h1>JavaDoc guidelines</h1>
  11.     <p>You should always comment your code thoroughly, or else others will have a hard time reading and/or using
  12.     your code. Here are some basic guidelines on how to write proper JavaDoc comments.</p>
  13.  
  14.     <h2>Methods</h2>
  15.     <p>When writing JavaDoc for methods, always provide descriptions for the actual <span class="mark_red">method</span>,
  16.     all the <span class="mark_red">parameters</span> and also the <span class="mark_red">return value</span>.
  17.     Here is a short example:</p>
  18.     <pre>
  19.         /**
  20.          * Here goes the function description. Be short, but precise.
  21.          * Wrap the lines so things look nice. Don't forget to finish
  22.         * every sentence with a dot (or else, JavaDoc tools might fail).
  23.         *
  24.         * @param someString Here goes a description for the
  25.         * "someString"-parameter. Wrap the lines as usual, and don't
  26.          * forget to comment what a value of "null" means (if the
  27.          * parameter is an Object that is).
  28.          *
  29.          * @param someInt Here goes the description for the "someInt"-
  30.          * parameter.
  31.          *
  32.          * @return Describe what the function returns here. Don't
  33.         * write this like "@return This method returns...", but
  34.         * instead something like this "@return the sum of A and B".
  35.         */
  36.        protected int myMethod(String someString, int someInt) {
  37.            this.someString = someString;
  38.        }
  39.    </pre>
  40.  
  41.    <h2>Classes</h2>
  42.    <p>You should always comment your actual classes, but you also need to keep in mind
  43.    that, within your class, <span class="mark_red">all public and protected fields and/or methods should have
  44.    proper JavaDoc comments</span> as well. The basic rule is to think about whether or not
  45.    anybody else might be using the function/field you're creating. If it is
  46.     declared private, you're the only one that will ever use it, so it's OK to provide
  47.     some basic comment, like:</p>
  48.     <pre>
  49.         //counts the number of sent packets
  50.         private int packetCounter;
  51.     </pre>
  52.     <p>However, if it is declared public of protected, you need to provide JavaDoc-compatible
  53.     comments, much like the method-example above. A field would then look like this instead:</p>
  54.     <pre>
  55.         /**
  56.          * Counts the number of sent packets.
  57.          */
  58.         public int packetCounter;
  59.     </pre>
  60.     <p>There is a special case though, if your field is protected or public inside a private inner
  61.     class, then nobody else will be able to use the inner class anyway, so you don't have to
  62.    that strict when writing inner classes. Simple comments will do. Now, here is a class example:</p>
  63.    <pre>
  64.        /**
  65.         * Class description goes here. Same procedure as for method
  66.         * descriptions.
  67.         *
  68.         * @author [Your name goes here] (If an @author-tag already exists,
  69.         * just add another one with your name, indicating that you
  70.         * have also participated writing the class)
  71.         */
  72.        class MyClass extends SomeOtherClass implements SomeInterfaces {
  73.  
  74.            //this is a private field, so no need to JavaDoc it!
  75.            private int myInt;
  76.  
  77.            /**
  78.             * This is a public or protected field, and thus, we must provide
  79.             * JavaDoc since somebody else might use this. Description
  80.             * of the field goes here.
  81.             */
  82.            protected String myString;
  83.  
  84.            //no need to JavaDoc this either. only if it would have
  85.            //been public or protected (in that case, use same format
  86.            //as for this outer class)
  87.            private class MyInnerClass {
  88.  
  89.                //ok, now this is public, but the inner class it belongs to
  90.                //is just private, so no need to JavaDoc this either
  91.                //(we're the only ones who're going to be able to use
  92.                //this anyway)
  93.                public String blabla;
  94.  
  95.            }
  96.  
  97.        }
  98.    </pre>
  99.    <p><span class="mark_red">If you're overriding a method that already has good JavaDoc comments you don't need to
  100.    provide new JavaDoc comments if you don't want to</span>. Only if you change the actual meaning
  101.     of the method will you have to provide new comments. However, if you're just modifying the
  102.    original method slightly, don't provide any comments at all. The JavaDoc tools will then use
  103.     the comments from the method in the superclass instead. Here is an example:</p>
  104.     <p>This superclass has proper JavaDoc comments for its methods already:</p>
  105.     <pre>
  106.         abstract class Module {
  107.             /**
  108.              * Gets the name of the module.
  109.              * @return The name of the module.
  110.              */
  111.             abstract public String getName();
  112.         }
  113.     </pre>
  114.     <p>And thus, an inheriting class doesn't need to provide its own JavaDoc comments for
  115.    the methods it overrides:</p>
  116.    <pre>
  117.        class MyModule extends Module {
  118.            public String getName() {
  119.                return "MyModule";
  120.            }
  121.        }
  122.    </pre>
  123.  
  124. </body>
  125. </html>