Wiki source code of CodeStyle

Version 19.1 by Anca Luca on 2009/11/02 16:54

Show last authors
1 #startfloatingbox()
2 *Contents*
3 #toc ("2" "3" "")
4 #endfloatingbox()
5
6 1 Code Style
7
8 The XWiki project is following a specific coding style. We're using [Checkstyle>http://checkstyle.sourceforge.net] ([checkstyle.xml>http://svn.xwiki.org/svnroot/xwiki/platform/xwiki-tools/trunk/xwiki-verification-resources/src/main/resources/checkstyle.xml]) to ensure compliance of the code. Our build (the Maven2 one) is configured to fail on violations. However the decision to follow this code style and enforce it was only made recently and not all the code base has been moved to this new code style. Hence:
9 * We're only enforcing the code style in the code that has been moved to the new code style. The checked files are defined in ~~xwiki/core/pom.xml~~ (bottom of file).
10 * We're asking new code to follow the new style and then once a Java file is compliant, to edit ~~xwiki/core/pom.xml~~ and add it there so that we cannot regress...
11
12 For examples of "clean" classes see the following classes and their unit tests:
13 * ZipExplorerPlugin*.java ([main sources>http://fisheye2.cenqua.com/browse/xwiki/platform/core/trunk/xwiki-core/src/main/java/com/xpn/xwiki/plugin/zipexplorer]|[tests>http://fisheye2.cenqua.com/browse/xwiki/platform/core/trunk/xwiki-core/src/test/java/com/xpn/xwiki/plugin/zipexplorer])
14 * XWikiMessageTool.java ([main sources>http://fisheye2.cenqua.com/browse/~raw,r=trunk/xwiki/platform/core/trunk/xwiki-core/src/main/java/com/xpn/xwiki/web/XWikiMessageTool.java]|[tests>http://fisheye2.cenqua.com/browse/xwiki/platform/core/trunk/xwiki-core/src/test/java/com/xpn/xwiki/web/XWikiMessageToolTest.java])
15
16 1.1 Configuring your IDE to use the XWiki code style
17
18 1.1.1 Eclipse 3.x
19
20 Download [codestyle-eclipse.xml>http://svn.xwiki.org/svnroot/xwiki/platform/xwiki-tools/trunk/xwiki-verification-resources/src/main/resources/codestyle-eclipse.xml].
21
22 After this, select ~~Window > Preferences~~, and open up the configuration for ~~Java > Code Style > Code Formatter~~. Click on the button labeled ~~Import...~~ and select the file you downloaded. Give the style a name, and click OK.
23
24 To reformat a file, press <tt>Ctrl+Shift+F</tt> while inside that file. To format only a portion of the file, select it and press the same key combination.
25
26 In recent versions of Eclipse (&ge;3.3) there is the possibility to configure Eclipse to automatically format a file when saving it. To do this, open ~~Window &gt; Preferences~~, select ~~Java &gt; Editor &gt; Save Actions~~ and enable ~~Perform the selected actions on save~~ and ~~Format source code~~.
27
28 Download [codetemplates-eclipse.xml>http://svn.xwiki.org/svnroot/xwiki/platform/xwiki-tools/trunk/xwiki-verification-resources/src/main/resources/codetemplates-eclipse.xml].
29
30 After this, select ~~Window > Preferences~~, and open up the configuration for ~~Java > Code Style > Code Templates~~. Click on the button labeled ~~Import...~~ and select the file you downloaded. You can enable "Automatically add comments for new methods and types" if you want.
31
32 To generate a javadoc, press <tt>Meta+Shift+J</tt> while on the element you want to document.
33
34 1.1.1 IntelliJ IDEA 4.5\+
35
36 Download [codestyle-idea.xml>http://svn.xwiki.org/svnroot/xwiki/platform/xwiki-tools/trunk/xwiki-verification-resources/src/main/resources/codestyle-idea.xml].
37
38 Close IntelliJ IDEA. Place the file in your IntelliJ IDEA user configuration directory. For example for Windows Vista users of IntelliJ IDEA v6.x, it's in ~~C:\\\Users\\\username\\\.IntelliJIdea60\\\config\\\codestyles~~. Then open IntelliJ IDEA again, select ~~File > Project Settings > Project Code Style~~, select ~~Use per-project code style scheme~~, click on ~~Import...~~ and select ~~XWiki~~.
39
40 1.1 Interface best practices
41
42 1.1.1 Do not use 'public' in interfaces
43
44 Public is always implied in interfaces. Do not write:
45
46 {code}
47 public interface Page
48 {
49 public String getParentSpaceKey();
50 }
51 {code}
52
53 But instead, write
54
55 {code}
56 public interface Page
57 {
58 String getParentSpaceKey();
59 }
60 {code}
61
62 1.1 Javadoc Best Practices
63
64 We are following the [Sun Javadoc coding conventions>http://java.sun.com/j2se/javadoc/writingdoccomments/]. Please make sure you're familiar with them when you write javadoc.
65
66 1.1.1 Write useful comments
67
68 Do not repeat name of method or any useless information. For example, if you have:
69
70 {code}
71 /**
72 * @return the id
73 */
74 public String getId()
75 {
76 return this.id;
77 }
78 {code}
79
80 Instead, write:
81
82 {code}
83 /**
84 * @return the attachment id (the id is the filename of the XWikiAttachment object used to construct this Attachment object)
85 */
86 public String getId()
87 {
88 return this.id;
89 }
90 {code}
91
92 1.1.1 Do not duplicate Javadoc
93
94 If you inherit from an interface then you shouldn't copy the Javadoc from the interface. Instead you should reference it. For example if ~~getSomething()~~ is the implementation a method defined in an inherited ~~Something~~ interface, you shouldn't write:
95
96 {code}
97 /**
98 * Do something blah blah.
99 */
100 public void doSomething()
101 {
102
103 [...]
104 {code}
105
106 Instead, write the following:
107
108 {code}
109 /**
110 * {@inheritDoc}
111 *
112 * <p>Optionally add here javadoc additional to the one inherited from the parent javadoc.</p>
113 *
114 * @see Something#doSomething()
115 */
116 public void doSomething()
117 {
118 [...]
119 {code}
120
121 1.1.1 Do not duplicate method comments with parameters comments
122
123 Instead of writing:
124
125 {code}
126 /**
127 * Returns the key of the space to which this page belongs to.
128 *
129 * @return - Parent space's key as String.
130 */
131 public String getParentSpaceKey();
132 {code}
133
134 Write:
135
136 {code}
137 /**
138 * @return the key of the space to which this page belongs to. For example "Main".
139 */
140 public String getParentSpaceKey();
141 {code}
142
143 1.1.1 Use version and since javadoc tags
144
145 For example:
146
147 {code}
148 /**
149 * Something, blah blah...
150 *
151 * @version $Id: $
152 * @since 1.6M1
153 */
154 {code}
155
156 #warning("Do not use author javadoc tags.")
157
158 1.1 Class/Interface names
159
160 * Prefix class names with <tt>Abstract</tt> for abstract classes
161 * Class names should start with an uppercase letter
162 * The interface name should be as short and expressive as possible with no technical prefix or suffix. For example "Parser".
163 ** As a consequence interfaces shouldn't be prefixed with "I" (as in "IParser") or suffixed with "Interface" (as in "ParserInterface"), nor suffixed with "IF" (as in "ParserIF).
164 * Classes implementing interfaces should extend the interface name by prefixing it with a characteristic of the implementation. For example "XWikiParser".
165 ** As a consequence implementation classes shouldn't be suffixed with "Impl", "Implementation", etc.
166 * Default implementation classes where there's only one implementation provided by XWiki should be prefixed with "Default". As in "DefaultParser".
167
168 1.1 Members and fields names
169
170 * All methods and fields names should be camelCase, starting with a lower letter (<tt>someProperty</tt>, <tt>getSomeProperty()</tt>)
171 * The names should be understandable and short, avoiding abbreviations (<tt>parentDocument</tt> instead of <tt>pdoc</tt>, for example)
172 * Constants should all be uppercase, with underscores as word separators, and no prefix letter (<tt>WIKI_PAGE_CREATOR</tt> instead of <tt>WIKIPAGECREATOR</tt>)
173 * Constants should be <tt>public/private static final</tt> in classes (<tt>public static final String CONTEXT_KEY = "theKey"</tt>) and without any modifiers in interfaces, since <tt>public</tt>, <tt>static</tt> and <tt>final</tt> are implied and enforced (<tt>String PREFERENCES_DOCUMENT_NAME = "XWiki.XWikiPreferences"</tt>)
174
175 1.1 Package names
176
177 * All code that is *not* moved to the new XWiki Architecture based on components should use <tt>com.xpn.xwiki</tt>. New architecture code should use <tt>org.xwiki</tt>.
178 * The package name for code using the component-based architecture must be of the format <tt>org.xwiki.(module name).*</tt>. For example <tt>org.xwiki.rendering</tt>.
179 * Non user-public code must be located in an <tt>internal</tt> package just after the module name. For example: <tt>org.xwiki.rendering.internal.parser.*</tt>. General rule is <tt>org.xwiki.(module name).internal.*</tt>
180
181
182 1.1 Logging Best Practices
183
184 * Your component must implement the LogEnabled interface or better extend AbstractLogEnabled. This gives it a getLogger() method it can use to log.
185 * You should use the severity according to the following rules:
186 ** *info*: used for logs that should be printed by default (default logging configuration)
187 ** *debug*: logs that are informational but that shouldn't be printed by default should be debug logs
188 ** *warning*: they are for not critical problems but raised so that the users see them and remedy the problem, shown by default too
189 ** *error*: they are for critical problems that cause the application to misbehave and should most of the time have an associated stack trace
190 * If you need to perform computations for passing parameters to the logging calls you should use the <tt>is*Enabled()</tt> methods in order not to reduce performances
191
192 1.1 XML Files Style Guidelines
193
194 The XML files should follow these rules:
195 * lines are 120 characters long (same as for the Java files)
196 * indentation uses 2 spaces

Get Connected