qpid-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache Qpid > AMQP 1.0 JMS Client Coding Standards
Date Tue, 04 Jun 2013 15:55:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/2042/9/21/_/styles/combined.css?spaceKey=qpid&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/qpid/AMQP+1.0+JMS+Client+Coding+Standards">AMQP
1.0 JMS Client Coding Standards</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~phil@philharveyonline.com">Phil
Harvey</a>
    </h4>
        <br/>
                         <h4>Changes (2)</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" >h4. Commenting incomplete code (TODO
etc) <br>Sometimes code needs to be commented to indicate that future modification is
intended. The comment marker to use depends on when that modification should happen: <br></td></tr>
            <tr><td class="diff-changed-lines" >||When <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">modification</span>
<span class="diff-added-words"style="background-color: #dfd;">remediation</span>
must happen||Comment marker|| <br></td></tr>
            <tr><td class="diff-unchanged" >|Before committing to SVN| {code}//
TODO-SVN{code}| <br>|Before the next release| {code}// TODO-RELEASE{code}| <br>|At
an unspecified time| {code}// TODO{code}| <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">
<br>The intention of this standard is to help distinguish between the different types
of &quot;TODO&quot; comment, e.g. to avoid committing code to SVN that was only added
for local debugging purposes. <br>Note that Java IDEs such as Eclipse can be configured
to recognise custom markers and assign them specific priorities. <br></td></tr>
    
            </table>
    </div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <div class='panelMacro'><table class='infoMacro'><colgroup><col
width='24'><col></colgroup><tr><td valign='top'><img src="/confluence/images/icons/emoticons/information.gif"
width="16" height="16" align="absmiddle" alt="" border="0"></td><td>This page
is essentially a proposal, created to help us reach consensus on specific standards that apply
to the JMS client work.</td></tr></table></div>

<p>Our main coding standards are at <a href="/confluence/display/qpid/Java+Coding+Standards"
title="Java Coding Standards">Java Coding Standards</a>.</p>

<p>The AMQP 1.0 JMS Client project mandates the following additional standards.</p>

<div>
<ul>
    <li><a href='#AMQP1.0JMSClientCodingStandards-Overridingmethodsfromjava.lang.Object'>Overriding
methods from java.lang.Object</a></li>
    <li><a href='#AMQP1.0JMSClientCodingStandards-Logging'>Logging</a></li>
    <li><a href='#AMQP1.0JMSClientCodingStandards-Commentingincompletecode%28TODOetc%29'>Commenting
incomplete code (TODO etc)</a></li>
</ul></div>

<h4><a name="AMQP1.0JMSClientCodingStandards-Overridingmethodsfromjava.lang.Object"></a>Overriding
methods from java.lang.Object</h4>

<ul>
	<li><b>toString()</b> implementations should use org.apache.commons.lang.builder.<b>ToStringBuilder</b>
with its <b>SHORT_PREFIX_STYLE</b>, for example:
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
    @Override
    <span class="code-keyword">public</span> <span class="code-object">String</span>
toString()
    {
        <span class="code-keyword">return</span> <span class="code-keyword">new</span>
ToStringBuilder(<span class="code-keyword">this</span>, ToStringStyle.SHORT_PREFIX_STYLE)
            .append(<span class="code-quote">"sendMessage"</span>, _sentMessage)
            .append(<span class="code-quote">"sender"</span>, _sender)
            .toString();
    }
</pre>
</div></div></li>
</ul>


<ul>
	<li><b>equals(Object)</b> should be implemented using org.apache.commons.lang.builder.EqualsBuilder</li>
	<li><b>hashCode()</b> should be implemented using org.apache.commons.lang.builder.HashCodeBuilder</li>
</ul>


<h4><a name="AMQP1.0JMSClientCodingStandards-Logging"></a>Logging</h4>
<ul>
	<li>SLF4J must be used for logging.</li>
	<li>Logger names should be based on the class name, e.g. 
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java"><span class="code-keyword">private</span> <span
class="code-keyword">static</span> <span class="code-keyword">final</span>
Logger _logger = LoggerFactory.getLogger(Main.class);</pre>
</div></div>
	<ul>
		<li>Logger names may use unconventional values in specialised cases, e.g. auditing
or timing.</li>
	</ul>
	</li>
</ul>


<h4><a name="AMQP1.0JMSClientCodingStandards-Commentingincompletecode%28TODOetc%29"></a>Commenting
incomplete code (TODO etc)</h4>
<p>Sometimes code needs to be commented to indicate that future modification is intended.
The comment marker to use depends on when that modification should happen:</p>
<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'>When remediation must happen</th>
<th class='confluenceTh'>Comment marker</th>
</tr>
<tr>
<td class='confluenceTd'>Before committing to SVN</td>
<td class='confluenceTd'> <div class="code panel" style="border-width: 1px;"><div
class="codeContent panelContent">
<pre class="code-java"><span class="code-comment">// TODO-SVN</span></pre>
</div></div></td>
</tr>
<tr>
<td class='confluenceTd'>Before the next release</td>
<td class='confluenceTd'> <div class="code panel" style="border-width: 1px;"><div
class="codeContent panelContent">
<pre class="code-java"><span class="code-comment">// TODO-RELEASE</span></pre>
</div></div></td>
</tr>
<tr>
<td class='confluenceTd'>At an unspecified time</td>
<td class='confluenceTd'> <div class="code panel" style="border-width: 1px;"><div
class="codeContent panelContent">
<pre class="code-java"><span class="code-comment">// TODO</span></pre>
</div></div></td>
</tr>
</tbody></table>
</div>


<p>The intention of this standard is to help distinguish between the different types
of "TODO" comment, e.g. to avoid committing code to SVN that was only added for local debugging
purposes.<br/>
Note that Java IDEs such as Eclipse can be configured to recognise custom markers and assign
them specific priorities.</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/qpid/AMQP+1.0+JMS+Client+Coding+Standards">View
Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=31823828&revisedVersion=2&originalVersion=1">View
Changes</a>
                |
        <a href="https://cwiki.apache.org/confluence/display/qpid/AMQP+1.0+JMS+Client+Coding+Standards?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org


Mime
View raw message