Subversion Repositories HomeAutomation

Rev

Rev 73 | Go to most recent revision | Blame | Compare with Previous | Last modification | View Log | SVN | RSS feed 

<html>

<head>
    <title>JavaDoc guidelines</title>
    <link rel="StyleSheet" href="doc.style.css" type="Text/CSS">
</head>

<body>

    <h1>JavaDoc guidelines</h1>
    <p>You should always comment your code thoroughly, or else others will have a hard time reading and/or using
    your code. Here are some basic guidelines on how to write proper JavaDoc comments.</p>

    <h2>Methods</h2>
    <p>When writing JavaDoc for methods, always provide descriptions for the actual <span class="mark_red">method</span>,
    all the <span class="mark_red">parameters</span> and also the <span class="mark_red">return value</span>.
    Here is a short example:</p>
    <pre>
        /**
         * Here goes the function description. Be short, but precise.
         * Wrap the lines so things look nice. Don't forget to finish
         * every sentence with a dot (or else, JavaDoc tools might fail).
         *
         * @param someString Here goes a description for the
         * "someString"-parameter. Wrap the lines as usual, and don't
         * forget to comment what a value of "null" means (if the
         * parameter is an Object that is).
         *
         * @param someInt Here goes the description for the "someInt"-
         * parameter.
         *
         * @return Describe what the function returns here. Don't
         * write this like "@return This method returns...", but
         * instead something like this "@return the sum of A and B".
         */
        protected int myMethod(String someString, int someInt) {
            this.someString = someString;
        }
    </pre>

    <h2>Classes</h2>
    <p>You should always comment your actual classes, but you also need to keep in mind
    that, within your class, <span class="mark_red">all public and protected fields and/or methods should have
    proper JavaDoc comments</span> as well. The basic rule is to think about whether or not
    anybody else might be using the function/field you're creating. If it is
    declared private, you're the only one that will ever use it, so it's OK to provide
    some basic comment, like:</p>
    <pre>
        //counts the number of sent packets
        private int packetCounter;
    </pre>
    <p>However, if it is declared public of protected, you need to provide JavaDoc-compatible
    comments, much like the method-example above. A field would then look like this instead:</p>
    <pre>
        /**
         * Counts the number of sent packets.
         */
        public int packetCounter;
    </pre>
    <p>There is a special case though, if your field is protected or public inside a private inner
    class, then nobody else will be able to use the inner class anyway, so you don't have to
    that strict when writing inner classes. Simple comments will do. Now, here is a class example:</p>
    <pre>
        /**
         * Class description goes here. Same procedure as for method
         * descriptions.
         *
         * @author [Your name goes here] (If an @author-tag already exists,
         * just add another one with your name, indicating that you
         * have also participated writing the class)
         */
        class MyClass extends SomeOtherClass implements SomeInterfaces {

            //this is a private field, so no need to JavaDoc it!
            private int myInt;

            /**
             * This is a public or protected field, and thus, we must provide
             * JavaDoc since somebody else might use this. Description
             * of the field goes here.
             */
            protected String myString;

            //no need to JavaDoc this either. only if it would have
            //been public or protected (in that case, use same format
            //as for this outer class)
            private class MyInnerClass {

                //ok, now this is public, but the inner class it belongs to
                //is just private, so no need to JavaDoc this either
                //(we're the only ones who're going to be able to use
                //this anyway)
                public String blabla;

            }

        }
    </pre>
    <p><span class="mark_red">If you're overriding a method that already has good JavaDoc comments you don't need to
    provide new JavaDoc comments if you don't want to</span>. Only if you change the actual meaning
    of the method will you have to provide new comments. However, if you're just modifying the
    original method slightly, don't provide any comments at all. The JavaDoc tools will then use
    the comments from the method in the superclass instead. Here is an example:</p>
    <p>This superclass has proper JavaDoc comments for its methods already:</p>
    <pre>
        abstract class Module {
            /**
             * Gets the name of the module.
             * @return The name of the module.
             */
            abstract public String getName();
        }
    </pre>
    <p>And thus, an inheriting class doesn't need to provide its own JavaDoc comments for
    the methods it overrides:</p>
    <pre>
        class MyModule extends Module {
            public String getName() {
                return "MyModule";
            }
        }
    </pre>

</body>
</html>