directory-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache Directory Development > Coding standards
Date Sun, 20 Jun 2010 15:12:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/1810/9/1/_/styles/combined.css?spaceKey=DIRxDEV&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="https://cwiki.apache.org/confluence/display/DIRxDEV/Coding+standards">Coding
standards</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~seelmann">Stefan
Seelmann</a>
    </h4>
        <br/>
                         <h4>Changes (1)</h4>
                                 
    
<div id="page-diffs">
            <table class="diff" cellpadding="0" cellspacing="0">
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >&amp;nbsp;{note:title=eclipse
IDE} <br> <br></td></tr>
            <tr><td class="diff-changed-lines" >Eclipse users can import those
two files to enfore the code formating : <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">[^formatting.xml]</span>
<span class="diff-added-words"style="background-color: #dfd;">[formatting.xml|http://svn.apache.org/repos/asf/directory/project/trunk/resources/formatting.xml]</span>
and <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">[^codetemplates.xml]</span>
<span class="diff-added-words"style="background-color: #dfd;">[codetemplates.xml|http://svn.apache.org/repos/asf/directory/project/trunk/resources/codetemplates.xml]</span>
<br></td></tr>
            <tr><td class="diff-unchanged" > <br> <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
        </table>
</div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <h1><a name="Codingstandards-Codingstandards"></a>Coding standards</h1>

<p>Welcome to you, developper &#33; You have been elected committer on the project,
or you want to contribute some code or some patch? This is great news. However, in order to
be able to share your 'vision' and your code, some rules must be followed.</p>

<p>Hey, remember that those rules are not the best nor the worst, they are pretty much
what they are for historical reasons, or for technical reasons, however, please, accept them
as they are, and avoid religious war (please, oh please, no mail to say "WTF ? You are using
spaces instead of tab ??? How stupid is this rule etc etc.) Rules are <b>always</b>
stupid, but smart people follow them <img class="emoticon" src="/confluence/images/icons/emoticons/wink.gif"
height="20" width="20" align="absmiddle" alt="" border="0"/></p>

<p>&nbsp;</p>
<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td
valign='top'><img src="/confluence/images/icons/emoticons/warning.gif" width="16" height="16"
align="absmiddle" alt="" border="0"></td><td><b>eclipse IDE</b><br
/>Eclipse users can import those two files to enfore the code formating : <a href="http://svn.apache.org/repos/asf/directory/project/trunk/resources/formatting.xml"
class="external-link" rel="nofollow">formatting.xml</a> and <a href="http://svn.apache.org/repos/asf/directory/project/trunk/resources/codetemplates.xml"
class="external-link" rel="nofollow">codetemplates.xml</a></td></tr></table></div>
<p>&nbsp;</p>

<p>&nbsp;</p>
<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td
valign='top'><img src="/confluence/images/icons/emoticons/warning.gif" width="16" height="16"
align="absmiddle" alt="" border="0"></td><td><b>IDEA IDE</b><br
/>IDEA users can import this file to enfore the code formating : <a href="/confluence/download/attachments/28988/settings.jar?version=1&amp;modificationDate=1163066567000">settings.jar</a></td></tr></table></div>
<p>&nbsp;</p>


<h2><a name="Codingstandards-Headers"></a>Headers</h2>

<p>First, you <b>must</b> (and this rule accept no exception) use this header
in top of all source file, or each file in which you can have comments :</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
/*
 *  Licensed to the Apache Software Foundation (ASF) under one
 *  or more contributor license agreements.  See the NOTICE file
 *  distributed with <span class="code-keyword">this</span> work <span class="code-keyword">for</span>
additional information
 *  regarding copyright ownership.  The ASF licenses <span class="code-keyword">this</span>
file
 *  to you under the Apache License, Version 2.0 (the
 *  <span class="code-quote">"License"</span>); you may not use <span class="code-keyword">this</span>
file except in compliance
 *  with the License.  You may obtain a copy of the License at
 *
 *    http:<span class="code-comment">//www.apache.org/licenses/LICENSE-2.0
</span> *
 *  Unless required by applicable law or agreed to in writing,
 *  software distributed under the License is distributed on an
 *  <span class="code-quote">"AS IS"</span> BASIS, WITHOUT WARRANTIES OR CONDITIONS
OF ANY
 *  KIND, either express or implied.  See the License <span class="code-keyword">for</span>
the
 *  specific language governing permissions and limitations
 *  under the License.
 *
 */
</pre>
</div></div>

<h3><a name="Codingstandards-Class%2FInterfaceheaders"></a>Class/Interface
headers</h3>

<p>Each <b>Class</b> or <b>Interface</b> should have an header
which must contains :</p>
<ul>
	<li>A descrption of this class/interface</li>
	<li>an <b>author</b> tag which should be :
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
@author &lt;a href=<span class="code-quote">"mailto:dev@directory.apache.org"</span>&gt;Apache
Directory Project&lt;/a&gt;
</pre>
</div></div>
<blockquote>
<p>Thanks to avoid to put your name. The code is not yours, and much more important,
but putting ypur name and e-mail, you will intimidate other developper ("Oh, no, I won't mess
with this code, it has been developped by XXXX &#33;") and second, you will receive mail
in three years even if you have stopped all commitment on the project (and those who have
sent you an e-mail will think that the project's memeber are not responsive...)</p></blockquote>
<p>If you use <b>html</b> tags, remember to escape '&lt;' and '&gt;'
characters...</p></li>
</ul>


<h3><a name="Codingstandards-Staticmembersandothermembers"></a>Static members
and other members</h3>

<p>Just add a sinle line javadoc comment like : <b>/</b>&#42; blah ...
&#42;/&#42; before each member</p>

<h3><a name="Codingstandards-Methods"></a>Methods</h3>

<p>Follow the standard <b>javadoc</b> rules : Description, <b>@param</b>,
<b>@exception</b> and <b>@return</b>. It should be enough. No <b>@tags</b>,
<b>@todo</b> tags, etc...</p>

<p>Escape <b>html</b> characters</p>

<h2><a name="Codingstandards-Comments%26nbsp%3B"></a>Comments&nbsp;</h2>

<p>No special rules, except that you should avoid :</p>
<ul>
	<li>Useless comments like : i++; /&#42; Increment i &#42;/</li>
	<li>Overusing comments : if you have to heavily comment a peice of code, then this
piece of code might be too complex ...</li>
	<li>Speading little comments all over a method : if possible, write blocs of comments.
The method header could hgenerally contains a full description of the code, and if it's not
the case, just consider your method might be too long &#33;</li>
	<li>Dead code commented. If it's dead, then put it in a cuffin. We use SVN, the Ressuscitator
&#33;</li>
</ul>


<p>Basically, use your common sense <img class="emoticon" src="/confluence/images/icons/emoticons/smile.gif"
height="20" width="20" align="absmiddle" alt="" border="0"/></p>

<h2><a name="Codingstandards-Naming%26nbsp%3B"></a>Naming&nbsp;</h2>

<p>Naming &#33; Sounds like Blaming <img class="emoticon" src="/confluence/images/icons/emoticons/smile.gif"
height="20" width="20" align="absmiddle" alt="" border="0"/>. Ok. We use <b>Sun(tm/c/r)</b>
style :</p>
<ul>
	<li>Constants are in UPPER CASE with accepted '_'</li>
	<li>Class starts with an uppercase and each starting word is upper cased. No '_', please
&#33;</li>
	<li>Methods starts with lower case and then follow the same rule than classes. No '_',
please &#33;</li>
	<li>Interfaces should not start with an 'I'</li>
	<li>Classes which implements an Interface must be followed by the postfix 'impl'</li>
	<li>Variables follow the method naming convention. No '_', please &#33;</li>
	<li>Use meaningfull names.</li>
	<li>No double letter variables like ii, jj etc...</li>
</ul>


<p>If you browse the code, you will see that many classes does not respect those rules.
That's life &#33; Don't fix it if you don't touch a class. If you are fixing a method
in a class, then you can change the code to respect the rules. Little by little, we may reach
a stable state where all the code respect the rules <img class="emoticon" src="/confluence/images/icons/emoticons/wink.gif"
height="20" width="20" align="absmiddle" alt="" border="0"/></p>

<p>&nbsp;Naming is really important for <b>APIs</b>. Be smart. If you
are not sure, ask.</p>

<h2><a name="Codingstandards-Spacesvstabs%26nbsp%3B"></a>Spaces vs tabs&nbsp;</h2>

<p><font color="#ff0000"><b>&nbsp;FOUR SPACES, NO TAB</b></font>.
<b>Final.</b></p>

<p>No discussion. Using tabs break diffs. Modify your <b>IDE</b> to insert
spaces when you use tabs, before it saves the file.</p>

<h2><a name="Codingstandards-Formatting%26nbsp%3B"></a>Formatting&nbsp;</h2>

<p>Use the&nbsp; <b>formatting.xml</b> file which can be found in the
<b>resources</b> directory in the root of the project. This is for <b>Eclipse</b>.
If you don't use eclipse, then translate the formating to your favorite <b>IDE</b></p>

<p>Use the <b>codetemplates.xml</b> file if you are using <b>Eclipse</b>
too. You will find it at the same location. It brings you some standard headers for new classes,
nex methods, etc.</p>

<p>Use <b>UTF-8</b> as a default for your files (except for properties,
thanks to <b>java</b>, which should be in <b>ISO-8859-1</b>). Forget
about exotic encoding...</p>

<p><font color="#ff0000"><b>&#42;DO NOT USE AN AUTOMATIC FORMATER FOR
COMMENTS &#33;&#33;&#33;&#42;</b></font> People spend a lot of
time making their comment looks like pretty, so if you just format them, you will have to
recover the previous comments...&nbsp;</p>

<p>Some general rules :</p>
<ul>
	<li>Always use '{' and '}' even for a single instruction, or if you have an empty block
(don't use ';' for empty blocks)</li>
	<li>No more than one instruction on a single line, the only exception is the '?' ':'
operation</li>
	<li>Use <b>this</b> to address the class variable if there is a risk of
confusion (for instanc eif you have a parameter with the same name.</li>
	<li>Don't add a 'a_', or 'the_' before a parameter's name to distinguish it from the
class variable which has the same name. Use <b>this</b> instead.</li>
	<li>Don't add <b>final</b> everywhere. Even if <b>final</b>
is a substitute for <b>const</b>, it's semantic is not clear enough that you use
it everywhere.</li>
	<li>Add spaces in method calls after '(' and before ')'</li>
	<li>'{' and '}' must be on the same column</li>
</ul>


<p>This is a code example :</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
    ...
    <span class="code-object">int</span> result = myMethod( param1, param2 )
    
    <span class="code-keyword">if</span> ( result &gt; 0 )
    {
        <span class="code-comment">// <span class="code-keyword">do</span>
something
</span>    }
    ...
</pre>
</div></div>


<h2><a name="Codingstandards-Imports%26nbsp%3B"></a>Imports&nbsp;</h2>

<p>Always declare all the classes you import, do not use <b>x.y.&#42;</b>&nbsp;</p>

<h2><a name="Codingstandards-Whatelse%3F%26nbsp%3B"></a>What else ?&nbsp;</h2>

<p>Well, this was a very short introduction about coding rules. Use commen sense, look
at what you see around you when adding some code, ask people about format, if you have a question.</p>

<p>That's it &#33; (I wait your comments, guys :-)&nbsp;</p>
    </div>
        <div id="commentsSection" class="wiki-content pageSection">
        <div style="float: right;">
            <a href="https://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
        </div>
        <a href="https://cwiki.apache.org/confluence/display/DIRxDEV/Coding+standards">View
Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=28988&revisedVersion=6&originalVersion=5">View
Changes</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message