Wiki source code of CodeStyle

Version 12.3 by Vincent Massol on 2009/03/17 10:44

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 decided recently and the code base has not all been moved to this new code style. Hence:
9 * We're only enforcing the code style in the code that have 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 1.1.1 IntelliJ IDEA 4.5\+
25
26 Download [codestyle-idea.xml>http://svn.xwiki.org/svnroot/xwiki/platform/xwiki-tools/trunk/xwiki-verification-resources/src/main/resources/codestyle-idea.xml].
27
28 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~~.
29
30
31
32
33 1.1 Package names
34
35 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>.
36
37 1.1 Interface best practices
38
39 1.1.1 Do not use 'public' in interfaces
40
41 Public is always implied in interfaces. Do not write:
42
43 {code}
44 public interface Page
45 {
46 public String getParentSpaceKey();
47 }
48 {code}
49
50 But instead, write
51
52 {code}
53 public interface Page
54 {
55 String getParentSpaceKey();
56 }
57 {code}
58
59 1.1 Javadoc Best Practices
60
61 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.
62
63 1.1.1 Write useful comments
64
65 Do not repeat name of method or any useless information. For example, if you have:
66
67 {code}
68 /**
69 * @return the id
70 */
71 public String getId()
72 {
73 return this.id;
74 }
75 {code}
76
77 Instead, write:
78
79 {code}
80 /**
81 * @return the attachment id (the id is the filename of the XWikiAttachment object used to construct this Attachment object)
82 */
83 public String getId()
84 {
85 return this.id;
86 }
87 {code}
88
89 1.1.1 Do not duplicate Javadoc
90
91 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:
92
93 {code}
94 /**
95 * Do something blah blah.
96 */
97 public void doSomething()
98 {
99
100 [...]
101 {code}
102
103 Instead, write the following:
104
105 {code}
106 /**
107 * {@inheritDoc}
108 *
109 * <p>Optionally add here javadoc additional to the one inherited from the parent javadoc.</p>
110 *
111 * @see Something#doSomething()
112 */
113 public void doSomething()
114 {
115 [...]
116 {code}
117
118 1.1.1 Do not duplicate method comments with parameters comments
119
120 Instead of writing:
121
122 {code}
123 /**
124 * Returns the key of the space to which this page belongs to.
125 *
126 * @return - Parent space's key as String.
127 */
128 public String getParentSpaceKey();
129 {code}
130
131 Write:
132
133 {code}
134 /**
135 * @return the key of the space to which this page belongs to. For example "Main".
136 */
137 public String getParentSpaceKey();
138 {code}
139
140 1.1.1 Use version and since javadoc tags
141
142 For example:
143
144 {code}
145 /**
146 * Something, blah blah...
147 *
148 * @version $Id: $
149 * @since 1.6M1
150 */
151 {code}
152
153 #warning("Do not use author javadoc tags.")
154
155 1.1 Class/Interface names
156
157 * Prefix class names with <tt>Abstract</tt> for abstract classes
158 * Class names should start with an uppercase letter
159 * Interface name should be as short and expressive as possible with no technical prefix or suffix. For example "Parser".
160 ** 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).
161 * Classes implementing interfaces should extend the interface name by prefixing it with a characteristic of the implementation. For example "XWikiParser".
162 ** As a consequence implementation classes shouldn't be suffixed with "Impl", "Implementation", etc.
163 * Default implementation classes where there's only one implementation provided by XWiki should be prefixed with "Default". As in "DefaultParser".
164
165 1.1 Package names
166
167 * 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>.
168 * Non user-public code must be located in an <tt>internal</tt> package. For example: <tt>org.xwiki.rendering.internal.parser.*</tt>

Get Connected