WebSVN – HomeAutomation – Diff – /trunk/MacBeth/Docs/JavaDoc.Guidelines.htm


<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>

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

Subversion Repositories HomeAutomation

(root)/trunk/MacBeth/Docs/JavaDoc.Guidelines.htm @ 73 – Rev 15 → 73