coding-guide-and-style.html (227 lines of code) (raw):
<!DOCTYPE html>
<!--
| Generated by Apache Maven Doxia Site Renderer 1.7 at 2016-04-15
| Rendered using Apache Maven Fluido Skin 1.5
-->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="Date-Revision-yyyymmdd" content="20160415" />
<meta http-equiv="Content-Language" content="en" />
<title>Apache Omid – Coding Guide</title>
<link rel="stylesheet" href="./css/apache-maven-fluido-1.5.min.css" />
<link rel="stylesheet" href="./css/site.css" />
<link rel="stylesheet" href="./css/print.css" media="print" />
<script type="text/javascript" src="./js/apache-maven-fluido-1.5.min.js"></script>
</head>
<body class="topBarEnabled">
<div id="topbar" class="navbar navbar-fixed-top ">
<div class="navbar-inner">
<div class="container" style="width: 100%;"><div class="nav-collapse">
<ul class="nav">
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Home <b class="caret"></b></a>
<ul class="dropdown-menu">
<li> <a href="index.html" title="Overview">Overview</a>
</li>
<li> <a href="license.html" title="License">License</a>
</li>
</ul>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Download <b class="caret"></b></a>
<ul class="dropdown-menu">
<li> <a href="https://bintray.com/yahoo/maven/omid" title="Download Omid">Download Omid</a>
</li>
<li> <a href="https://bintray.com/yahoo/maven/omid" title="Bintray Repository">Bintray Repository</a>
</li>
</ul>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">User Guide & API <b class="caret"></b></a>
<ul class="dropdown-menu">
<li> <a href="quickstart.html" title="Quickstart">Quickstart</a>
</li>
<li> <a href="basic-examples.html" title="API and Code Examples">API and Code Examples</a>
</li>
</ul>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Technical Docs <b class="caret"></b></a>
<ul class="dropdown-menu">
<li> <a href="basic-concepts.html" title="Basic Concepts">Basic Concepts</a>
</li>
<li> <a href="omid-components.html" title="Omid Components">Omid Components</a>
</li>
<li> <a href="basic-algorithm.html" title="Basic Algorithm">Basic Algorithm</a>
</li>
<li> <a href="client-failure-management.html" title="Management of Client Failures">Management of Client Failures</a>
</li>
<li> <a href="http://yahoohadoop.tumblr.com/tagged/HBase" title="Blog Entries">Blog Entries</a>
</li>
</ul>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Contribute <b class="caret"></b></a>
<ul class="dropdown-menu">
<li> <a href="https://git-wip-us.apache.org/repos/asf/incubator-omid.git" title="Source Code">Source Code</a>
</li>
<li> <a href="https://issues.apache.org/jira/browse/Omid" title="JIRA">JIRA</a>
</li>
<li> <a href="mailing-lists.html" title="Mailing Lists">Mailing Lists</a>
</li>
<li> <a href="coding-guide-and-style.html" title="Coding Guide and Style">Coding Guide and Style</a>
</li>
</ul>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Project Reports <b class="caret"></b></a>
<ul class="dropdown-menu">
<li class="dropdown-submenu">
<a href="project-info.html" title="Project Information">Project Information</a>
<ul class="dropdown-menu">
<li> <a href="dependency-convergence.html" title="Dependency Convergence">Dependency Convergence</a>
</li>
<li> <a href="dependency-info.html" title="Dependency Information">Dependency Information</a>
</li>
<li> <a href="dependency-management.html" title="Dependency Management">Dependency Management</a>
</li>
<li> <a href="distribution-management.html" title="Distribution Management">Distribution Management</a>
</li>
<li> <a href="index.html" title="About">About</a>
</li>
<li> <a href="license.html" title="Licenses">Licenses</a>
</li>
<li> <a href="modules.html" title="Project Modules">Project Modules</a>
</li>
<li> <a href="plugin-management.html" title="Plugin Management">Plugin Management</a>
</li>
<li> <a href="plugins.html" title="Plugins">Plugins</a>
</li>
<li> <a href="team-list.html" title="Team">Team</a>
</li>
<li> <a href="source-repository.html" title="Source Code Management">Source Code Management</a>
</li>
<li> <a href="project-summary.html" title="Summary">Summary</a>
</li>
</ul>
</li>
</ul>
</li>
</ul>
<form id="search-form" action="https://www.google.com/search" method="get" class="navbar-search pull-right" >
<input value="omid.incubator.apache.org" name="sitesearch" type="hidden"/>
<input class="search-query" name="q" id="query" type="text" />
</form>
<script type="text/javascript" src="https://cse.google.com/brand?form=search-form"></script>
<ul class="nav pull-right"><li>
<a href="https://twitter.com/apacheomid" class="twitter-follow-button" data-show-count="true" data-align="right" data-size="large" data-show-screen-name="true" data-lang="en">Follow apacheomid</a>
<script type="text/javascript">!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0];if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src="//platform.twitter.com/widgets.js";fjs.parentNode.insertBefore(js,fjs);}}(document,"script","twitter-wjs");</script>
</li></ul>
</div>
</div>
</div>
</div>
<div class="container">
<div id="banner">
<div class="pull-left">
<a href="./" id="bannerLeft">
<img src="images/omid-logo.png" alt="Omid" width="200"/>
</a>
</div>
<div class="pull-right"> <a href="http://incubator.apache.org/" id="bannerRight">
<img src="http://incubator.apache.org/images/egg-logo2.png" alt="Apache Incubator" width="200"/>
</a>
</div>
<div class="clear"><hr/></div>
</div>
<div id="breadcrumbs">
<ul class="breadcrumb">
<li id="projectVersion">Version: 0.8.1.37-SNAPSHOT
</li>
<li id="publishDate" class="pull-right">Last Published: 2016-04-15</li>
</ul>
</div>
<div id="bodyColumn" >
<h1>Coding Guide</h1>
<p>The basic principle is to always write code that is testable, easy to understand, extensible, resistant to bugs. Code is written once but read by many people so we need to focus also on the next person that will read it:</p>
<ul>
<li>Keep it simple</li>
<li>Test your code</li>
<li><a class="externalLink" href="http://programmer.97things.oreilly.com/wiki/index.php/The_Single_Responsibility_Principle">Single responsibility principle</a></li>
<li>Try to maintain components <a class="externalLink" href="http://programmer.97things.oreilly.com/wiki/index.php/Cohesion_and_Coupling_matter">loosely coupled</a></li>
<li>Do not abuse of comments:
<ul>
<li>Choose names that reveal intent for modules, packages, classes, methods, variables, constants, etc.</li>
<li>Do not use comments for excuse bad code or when appropriate naming is enough</li>
<li>Comments are good when they provide context (Explain why, not how) or explain things that happen in the real world</li>
</ul></li>
<li>Follow the <a class="externalLink" href="http://programmer.97things.oreilly.com/wiki/index.php/The_Boy_Scout_Rule">Boy Scout Rule</a></li>
<li>Don’t reinvent the wheel:
<ul>
<li>Use patterns when possible</li>
<li>Use proven libraries for (e.g. Apache commons, guava, etc.)</li>
</ul></li>
<li>Refactor when necessary
<ul>
<li>When adding a new feature and the context is not appropriate, refactor first in a separate commit/s</li>
</ul></li>
</ul>
<h1>Coding Style</h1>
<p>Omid coding style shoud follow <a class="externalLink" href="http://www.oracle.com/technetwork/java/javase/documentation/codeconvtoc-136057.html">Oracle’s Code Conventions for Java</a>, with the following modifications:</p>
<ul>
<li>Lines can be up to 120 characters long</li>
<li>Indentation should be:
<ul>
<li>4 spaces</li>
<li>Tabs not allowed</li>
</ul></li>
<li>Always use curly braces for code blocks, even for single-line ‘ifs’ and ‘elses’</li>
<li>Do not include @author tags in any javadoc</li>
<li>Use TestNG for testing</li>
<li>Import ordering and spacing:
<ul>
<li>Try to organize imports alphabetically in blocks with this format:
<ul>
<li>A first block of imports from external libraries</li>
<li>A second block of imports from Java libraries</li>
<li>Finally a third block with <tt>static</tt> imports</li>
</ul></li>
<li>Example:</li>
</ul></li>
</ul>
<div class="source">
<div class="source"><pre class="prettyprint"> import com.google.common.base.Charsets;
import com.yahoo.omid.zk.ZKUtils.ZKException;
import com.yahoo.statemachine.StateMachine.Event;
import com.yahoo.statemachine.StateMachine.Fsm;
import com.yahoo.statemachine.StateMachine.State;
import org.apache.commons.configuration.Configuration;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
...
import java.io.IOException;
import java.net.InetSocketAddress;
import java.util.ArrayDeque;
...
import static com.yahoo.omid.ZKConstants.CURRENT_TSO_PATH;
import static com.yahoo.omid.zk.ZKUtils.provideZookeeperClient;
...
</pre></div></div>
</div>
</div>
<hr/>
<footer>
<div class="container">
<div class="row">
<p >Copyright © 2011–2016
<a href="http://www.apache.org">Apache Software Foundation</a>.
All rights reserved.
</p>
</div>
<p id="poweredBy" class="pull-right">
<a href="http://maven.apache.org/" title="Maven" class="builtBy">
<img class="builtBy" alt="Maven" src="http://maven.apache.org/images/logos/maven-feather.png" />
</a>
</p>
</div>
</footer>
</body>
</html>