| <!DOCTYPE html> |
| <html lang="en"> |
| <head> |
| <meta charset="utf-8"> |
| <meta name="viewport" content="width=device-width,initial-scale=1.0"> |
| <title>Apache Cassandra | Apache Cassandra Documentation</title> |
| <link rel="stylesheet" href="../../assets/css/site.css"> |
| <link rel="schema.dcterms" href="https://purl.org/dc/terms/"> |
| <meta name="dcterms.subject" content="_"> |
| <meta name="dcterms.identifier" content="master"> |
| <meta name="generator" content="Antora 2.3.4"> |
| <link rel="icon" href="../../assets/img/favicon.ico" type="image/x-icon"> |
| <script> |
| const script = document.createElement("script"); |
| const domain = window.location.hostname; |
| script.type = "text/javascript"; |
| script.src = "https://plausible.cassandra.apache.org/js/plausible.js"; |
| script.setAttribute("data-domain",domain); |
| script.setAttribute("defer",'true'); |
| script.setAttribute("async",'true'); |
| document.getElementsByTagName("head")[0].appendChild(script); |
| </script> </head> |
| <body class="basic "> |
| <div class="container mx-auto relative"> |
| <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"></script> |
| <meta property="og:type" content="website" /> |
| <meta property="og:url" content="/" /> |
| <meta property="og:site_name" content="Apache Cassandra" /> |
| |
| <header id="top-nav"> |
| <div class="inner relative"> |
| <div class="header-social-icons text-right"> |
| <a href="https://twitter.com/cassandra?lang=en" target="_blank" styles="margin-left: 20px;"><img src="../../assets/img/twitter-icon-circle-white.svg" alt="twitter icon" width="24"></a> |
| <a href="https://www.linkedin.com/company/apache-cassandra/" target="_blank" styles="margin-left: 20px;"><img src="../../assets/img/LI-In-Bug.png" alt="linked-in icon" width="24"></a> |
| <a href="https://www.youtube.com/c/PlanetCassandra" target="_blank" styles="margin-left: 20px;"><img src="../../assets/img/youtube-icon.png" alt="youtube icon" width="24"></a> |
| </div> |
| <div class="cf"> |
| <div class="logo left"><a href="/"><img src="../../assets/img/logo-white-r.png" alt="cassandra logo"></a></div> |
| <div class="mobile-nav-icon right"> |
| <img class="toggle-icon" src="../../assets/img/hamburger-nav.svg"> |
| </div> |
| <ul class="main-nav nav-links right flex flex-vert-center flex-space-between"> |
| <li> |
| <a class="nav-link hide-mobile">Get Started</a> |
| <ul class="sub-menu bg-white"> |
| <li class="pa-micro"> |
| <a href="/_/cassandra-basics.html"> |
| <div class="sub-nav-icon"> |
| <img src="../../assets/img/sub-menu-basics.png" alt="cassandra basics icon"> |
| </div> |
| <div class="sub-nav-text teal py-small"> |
| Cassandra Basics |
| </div> |
| </a> |
| </li> |
| <li class="pa-micro"> |
| <a href="/_/quickstart.html"> |
| <div class="sub-nav-icon"> |
| <img src="../../assets/img/sub-menu-rocket.png" alt="cassandra basics icon"> |
| </div> |
| <div class="sub-nav-text teal py-small"> |
| Quickstart |
| </div> |
| </a> |
| </li> |
| <li class="pa-micro"> |
| <a href="/_/ecosystem.html"> |
| <div class="sub-nav-icon"> |
| <img src="../../assets/img/sub-menu-ecosystem.png" alt="cassandra basics icon"> |
| </div> |
| <div class="sub-nav-text teal py-small"> |
| Ecosystem |
| </div> |
| </a> |
| </li> |
| </ul> |
| </li> |
| <li><a class="nav-link" href="/doc/latest/">Documentation</a></li> |
| <li> |
| <a class="nav-link" href="/_/community.html">Community</a> |
| <ul class="sub-menu bg-white"> |
| <li class="pa-micro"> |
| <a href="/_/community.html#code-of-conduct"> |
| <div class="sub-nav-icon"> |
| <img src="../../assets/img/sub-menu-welcome.png" alt="welcome icon"> |
| </div> |
| <div class="sub-nav-text teal py-small"> |
| Welcome |
| </div> |
| </a> |
| </li> |
| <li class="pa-micro hide-mobile"> |
| <a href="/_/community.html#discussions"> |
| <div class="sub-nav-icon"> |
| <img src="../../assets/img/sub-menu-discussions.png" alt="discussions icon"> |
| </div> |
| <div class="sub-nav-text teal py-small"> |
| Discussions |
| </div> |
| </a> |
| </li> |
| <li class="pa-micro hide-mobile"> |
| <a href="/_/community.html#project-governance"> |
| <div class="sub-nav-icon"> |
| <img src="../../assets/img/sub-menu-governance.png" alt="Governance icon"> |
| </div> |
| <div class="sub-nav-text teal py-small"> |
| Governance |
| </div> |
| </a> |
| </li> |
| <li class="pa-micro hide-mobile"> |
| <a href="/_/community.html#how-to-contribute"> |
| <div class="sub-nav-icon"> |
| <img src="../../assets/img/sub-menu-contribute.png" alt="Contribute icon"> |
| </div> |
| <div class="sub-nav-text teal py-small"> |
| Contribute |
| </div> |
| </a> |
| </li> |
| <li class="pa-micro hide-mobile"> |
| <a href="/_/community.html#meet-the-community"> |
| <div class="sub-nav-icon"> |
| <img src="../../assets/img/sub-menu-community.png" alt="Meet the Community icon"> |
| </div> |
| <div class="sub-nav-text teal py-small"> |
| Meet the Community |
| </div> |
| </a> |
| </li> |
| <li class="pa-micro hide-mobile"> |
| <a href="/_/cassandra-catalyst-program.html"> |
| <div class="sub-nav-icon"> |
| <img src="../../assets/img/sub-menu-catalyst.png" alt="Catalyst icon"> |
| </div> |
| <div class="sub-nav-text teal py-small"> |
| Catalyst Program |
| </div> |
| </a> |
| </li> |
| <li class="pa-micro hide-mobile"> |
| <a href="/_/events.html"> |
| <div class="sub-nav-icon"> |
| <img src="../../assets/img/sub-menu-events.png" alt="Events icon"> |
| </div> |
| <div class="sub-nav-text teal py-small"> |
| Events |
| </div> |
| </a> |
| </li> |
| </ul> |
| </li> |
| <li> |
| <a class="nav-link hide-mobile">Learn</a> |
| <ul class="sub-menu bg-white"> |
| <li class="pa-micro"> |
| <a href="/_/Apache-Cassandra-5.0-Moving-Toward-an-AI-Driven-Future.html"> |
| <div class="sub-nav-icon"> |
| <img src="../../assets/img/sub-menu-basics.png" alt="Basics icon"> |
| </div> |
| <div class="sub-nav-text teal py-small"> |
| Cassandra 5.0 |
| </div> |
| </a> |
| </li> |
| <li class="pa-micro"> |
| <a href="/_/case-studies.html"> |
| <div class="sub-nav-icon"> |
| <img src="../../assets/img/sub-menu-case-study.png" alt="Case Studies icon"> |
| </div> |
| <div class="sub-nav-text teal py-small"> |
| Case Studies |
| </div> |
| </a> |
| </li> |
| <li class="pa-micro"> |
| <a href="/_/resources.html"> |
| <div class="sub-nav-icon"> |
| <img src="../../assets/img/sub-menu-resources.png" alt="Resources icon"> |
| </div> |
| <div class="sub-nav-text teal py-small"> |
| Resources |
| </div> |
| </a> |
| </li> |
| <li class="pa-micro"> |
| <a href="/_/blog.html"> |
| <div class="sub-nav-icon"> |
| <img src="../../assets/img/sub-menu-blog.png" alt="Blog icon"> |
| </div> |
| <div class="sub-nav-text teal py-small"> |
| Blog |
| </div> |
| </a> |
| </li> |
| </ul> |
| </li> |
| <li><a class="nav-link btn btn--filled" href="/_/download.html">Download Now</a></li> |
| </ul> |
| </div> |
| </div> |
| </header> |
| |
| <div class="hero hero--home grad"> |
| <div class="eye"></div> |
| <div id="home-content" class="text-center flex flex-center flex-column relative z2 ma-xlarge"> |
| <h1>Code Style</h1> |
| </div> |
| </div> |
| <div class="flex-center py-large arrow"> |
| <div class="inner inner--narrow"> |
| <div id="preamble"> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>The Cassandra project follows |
| <a href="http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html">Sun’s Java |
| coding conventions</a> for anything not expressly outlined in this document.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Note that the project has a variety of styles that have accumulated in different subsystems. Where possible a balance should be struck between these guidelines and the style of the code that is being modified as part of a patch. Patches should also limit their scope to the minimum necessary for safely addressing the concerns of the patch.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="checkstyle"><a class="anchor" href="#checkstyle"></a>Checkstyle</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Cassandra uses <a href="https://checkstyle.sourceforge.io/">Checkstyle</a> project for enforcing various checkstyle policies the project follows. Checkstyle is part of the build from Cassandra 4.1 included. |
| You can consult the checkstyle configuration file called <code>checkstyle.xml</code> for the source code in <code>src</code> directory and <code>checkstyle_test.xml</code> for all code in <code>test</code> directory. |
| The configuration files are located in the root of the Cassandra repository. Checkstyle can be executed independently for the main source code as well as for the tests by executing <code>ant checkstyle</code> and <code>ant checkstyle-test</code> respectively.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The checkstyle target is executed by default when e.g. <code>build</code> or <code>jar</code> targets are executed. There is a flag you can use for <em>not</em> enforcing checkstyle. This is particularly handy upon development. |
| For example, by default, the checkstyle target checks that your changes in Java code do not include imports which are not used. |
| However, while you develop, you do not want this check to be enforced because you are not interested in it while you develop as your code tends to be in the in-progress state. |
| You can turn whole checkstyle off by specifying <code>-Dno-checkstyle=true</code> on the command line, for example like this: <code>ant build -Dno-checkstyle=true</code>.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="naming-and-clear-semantics"><a class="anchor" href="#naming-and-clear-semantics"></a>Naming and Clear Semantics</h2> |
| <div class="sectionbody"> |
| <div class="sect3"> |
| <h4 id="class-method-and-variable-naming"><a class="anchor" href="#class-method-and-variable-naming"></a>Class, Method and Variable Naming</h4> |
| <div class="paragraph"> |
| <p>Avoid extraneous words, for example prefer <code>x()</code> over <code>getX()</code> or <code>setX()</code> where it makes semantic sense. At the same time, do not avoid using words that are necessary, for example if a descriptive word provides semantic context such as <code>liveReplicas</code> over <code>replicas</code>. This is essential when there are many conceptual instantiations for a variable that are not enforced by the type system, but be sure to be consistent in the word choice and order across all instantiations of the variable.</p> |
| </div> |
| <div class="paragraph"> |
| <p>e.g. <em>allReplicas</em>, <em>naturalReplicas</em>, <em>pendingReplicas</em>, <em>allLiveReplicas</em>, etc.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="method-and-variable-naming-consistency"><a class="anchor" href="#method-and-variable-naming-consistency"></a>Method and Variable Naming Consistency</h4> |
| <div class="paragraph"> |
| <p>Ensure consistency of naming within a method, and between methods. It may be that multiple names are appropriate for a concept, but these should not be mixed and matched within the project. If you modify a concept, or improve the naming of a concept, make all relevant - including existing - code consistent with the new terminology. If possible, correspond with a prior author before modifying their semantics.</p> |
| </div> |
| <div class="sect4"> |
| <h5 id="standard-word-meanings-in-method-or-property-names"><a class="anchor" href="#standard-word-meanings-in-method-or-property-names"></a>Standard word meanings in method or property names</h5> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 50%;"> |
| <col style="width: 50%;"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>calculateX</code>,<code>computeX</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Perform some potentially expensive work to produce x</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>refreshX</code>,<code>updateX</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Recompute a memoized x</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>lookupX</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Find x in a map, or other structure, that is efficient but not free</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>x</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return x, relatively cheaply</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>toX</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return a potentially expensive translation to x</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>asX</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return a cheap translation to x</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>asXView</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Return a cheap translation to x, that will reflect changes in the source</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>isX</code>, <code>hasX</code>, <code>canX</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Boolean property or method indicating a capability or logical state</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>For boolean variables, fields and methods, choose names that sound like predicates and cannot be confused with nouns.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="semantic-distinctions-via-the-type-system"><a class="anchor" href="#semantic-distinctions-via-the-type-system"></a>Semantic Distinctions via the Type System</h4> |
| <div class="paragraph"> |
| <p>If possible, enforce semantic distinctions at compile time with the type system.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>e.g. <code>RangesAtEndpoint</code>, <code>EndpointsForRange</code> and <code>EndpointsForToken</code> are all semantically different variants on a collection of replicas.</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>This makes the intent of the code clearer, and helps the compiler indicate where we may have unintentionally conflated concepts. They also provide opportunities to insert stronger runtime checks that our assumptions hold, and these constraints can provide further clarity when reading the code.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>In the case of <code>EndpointsForX</code>, for instance, we enforce that we have no duplicate endpoints, and that all of the endpoints do fully cover X.</em></p> |
| </div> |
| <div class="sect4"> |
| <h5 id="enums-for-boolean-properties"><a class="anchor" href="#enums-for-boolean-properties"></a>Enums for Boolean Properties</h5> |
| <div class="paragraph"> |
| <p>Prefer an <code>enum</code> to <code>boolean</code> properties and parameters, unless clarity will be harmed (e.g. helper methods that accept a computed boolean predicate result, of the same name as used in the method they assist). Try to balance name clashes that would affect static imports, against clear and simple names that represent the behavioural switch.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="semantic-distinctions-via-member-variables"><a class="anchor" href="#semantic-distinctions-via-member-variables"></a>Semantic Distinctions via Member Variables</h4> |
| <div class="paragraph"> |
| <p>If a separate type for all concepts is too burdensome, a type that aggregates concepts together within member variables might be applicable.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The most obvious counter-example is not to use <code>Pair</code>, or a similar tuple. Unless it is extremely obvious, prefer a dedicated type with well named member variables.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>For example, <code>FetchReplicas</code> for source and target replicas, and <code>ReplicaLayout</code> for the distinction between natural and pending replicas.</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>This may help authors notice other semantics they had overlooked, that might have led to subtly incorrect parameter provision to methods. Conversely, methods may choose to accept one of these encapsulating types, so that callers do not need to consider which member they should provide.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>e.g. <code>ConsistencyLevel.assureSufficientLiveReplicas</code> requires very specific replica collections, that are quite distinct, that might be easily incorrectly provided (though this is still inadequate, as it needs to distinguish between live and non-live semantics, which remains to be improved)</em></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="public-apis"><a class="anchor" href="#public-apis"></a>Public APIs</h4> |
| <div class="paragraph"> |
| <p>These considerations are especially important for public APIs, including CQL, virtual tables, JMX, yaml, system properties, etc. Any planned additions must be carefully considered in the context of any existing APIs. Where possible the approach of any existing API should be followed. Where the existing API is poorly suited, a strategy should be developed to modify or replace the existing API with one that is more coherent in light of the changes - which should also carefully consider any planned or expected future changes to minimise churn. Any strategy for modifying APIs should be brought to <a href="mailto:dev@cassandra.apache.org">dev@cassandra.apache.org</a> for discussion.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="code-structure"><a class="anchor" href="#code-structure"></a>Code Structure</h2> |
| <div class="sectionbody"> |
| <div class="sect3"> |
| <h4 id="necessity"><a class="anchor" href="#necessity"></a>Necessity</h4> |
| <div class="paragraph"> |
| <p>If an interface has only one implementation, remove it. If a method isn’t used, delete it.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Don’t implement <code>hashCode()</code>, <code>equals()</code>, <code>toString()</code> or other methods unless they provide immediate utility.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="specificity"><a class="anchor" href="#specificity"></a>Specificity</h4> |
| <div class="paragraph"> |
| <p>Don’t overgeneralise. Implement the most specific method or class that you can, that handles the present use cases.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Methods and classes should have a single clear purpose, and should avoid special-cases where practical.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="class-layout"><a class="anchor" href="#class-layout"></a>Class Layout</h4> |
| <div class="paragraph"> |
| <p>Consider where your methods and inner classes live with respect to each other. Methods that are of a similar category should be adjacent, as should methods that are primarily dependent on each other. Try to use a consistent pattern, e.g. helper methods may occur either before or after the method that uses them, but not both; method signatures that cover different combinations of parameters should occur in a consistent order visiting the parameter space.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Class declaration order should, approximately, go: inner classes, static properties, instance properties, constructors (incl static factory methods), getters/setters, main functional/API methods, helper (incl static) methods and classes. Clarity should always come first, however.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="method-clarity"><a class="anchor" href="#method-clarity"></a>Method Clarity</h4> |
| <div class="paragraph"> |
| <p>A method should be short. There is no hard size limit, but a filled screen is a good warning size. However, be careful not to over-minimise your methods; a page of tiny functions is also hard to read.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The body of a method should be limited to the main conceptual work being done. Substantive ancillary logic, such as computing an intermediate result, evaluating complex predicates, performing auditing, logging, etc, are prime candidates for helper methods.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="compiler-assistance"><a class="anchor" href="#compiler-assistance"></a>Compiler Assistance</h4> |
| <div class="paragraph"> |
| <p>Always use <code>@Override</code> annotations when implementing abstract or interface methods or overriding a parent method.</p> |
| </div> |
| <div class="paragraph"> |
| <p><code>@Nullable</code>, <code>@NonNull</code>, <code>@ThreadSafe</code>, <code>@NotThreadSafe</code> and <code>@Immutable</code> should be used as appropriate to communicate to both the compiler and readers.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="boilerplate"><a class="anchor" href="#boilerplate"></a>Boilerplate</h4> |
| <div class="paragraph"> |
| <p>Prefer <code>public final</code> fields to private fields with getters (but prefer encapsulating behavior in "real" methods to either).</p> |
| </div> |
| <div class="paragraph"> |
| <p>Declare class properties <code>final</code> wherever possible, but never declare local variables and parameters <code>final</code>. Variables and parameters should still be treated as immutable wherever possible, with explicit code blocks introduced as necessary to minimize the scope of any mutable variables.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Prefer initialization in a constructor to setters, and builders where the constructor is complex with many optional parameters.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Avoid redundant <code>this</code> references to member fields or methods, except for consistency with other assignments e.g. in the constructor</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="exception-handling"><a class="anchor" href="#exception-handling"></a>Exception handling</h4> |
| <div class="paragraph"> |
| <p>Never ever write <code>catch (…)</code> {} or <code>catch (…) { logger.error() }</code> merely to satisfy Java’s compile-time exception checking.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Always catch the narrowest exception type possible for achieving your goal. If Throwable must be caught for handling exceptional termination, it must be rethrown. If an exception cannot be safely handled locally, propagate it - but use unchecked exceptions if no caller expects to handle the case. Rethrow as <code>RuntimeException</code>, <code>IOError</code>, or your own <code>UncheckedXException</code>, or <code>IllegalStateException</code> if it “can’t happen”</p> |
| </div> |
| <div class="paragraph"> |
| <p>Only if an exception is an explicitly acceptable condition can it be ignored, but this must be explained carefully in a comment detailing how this is handled correctly.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="formatting"><a class="anchor" href="#formatting"></a>Formatting</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p><code>{</code> and <code>}</code> are placed on a new line except when empty or opening a multi-line lambda expression. Braces may be elided to a depth of one if the condition or loop guards a single expression.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Lambda expressions accepting a single parameter should elide the braces that encapsulate the parameter. E.g. <code>x → doSomething()</code> and <code>(x, y) → doSomething()</code></p> |
| </div> |
| <div class="sect3"> |
| <h4 id="multiline-statements"><a class="anchor" href="#multiline-statements"></a>Multiline statements</h4> |
| <div class="paragraph"> |
| <p>Where possible prefer keeping a logical action to a single line. Prefer introducing additional variables, or well-named methods encapsulating actions, to multi-line statements - unless this harms clarity (e.g. in an already short method).</p> |
| </div> |
| <div class="paragraph"> |
| <p>Try to keep lines under 120 characters, but use good judgment. It is better to exceed this limit, than to split a line that has no natural splitting points, particularly when the remainder of the line is boilerplate or easily inferred by the reader.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If a line wraps inside a method call, first extract any long parameter expressions to local variables before trying to group natural parameters together on a single line, aligning the start of parameters on each line, e.g.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">Type newType = new Type(someValueWithLongName, someOtherRelatedValueWithLongName, |
| someUnrelatedValueWithLongName, |
| someDoublyUnrelatedValueWithLongName);</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>When splitting a ternary, use one line per clause, carry the operator, and where possible align the start of the ternary condition, e.g.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">var = bar == null |
| ? doFoo() |
| : doBar();</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>It is usually preferable to carry the operator for multiline expressions, with the exception of some multiline string literals.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="whitespace"><a class="anchor" href="#whitespace"></a>Whitespace</h4> |
| <div class="paragraph"> |
| <p>Make sure to use 4 spaces instead of the tab character for all your indentation. |
| Many lines in the current files have a bunch of trailing whitespace. If you encounter incorrect whitespace, clean up in a separate patch. Current and future reviewers won’t want to review whitespace diffs.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="static-imports"><a class="anchor" href="#static-imports"></a>Static Imports</h4> |
| <div class="paragraph"> |
| <p>Consider using static imports for frequently used utility methods that are unambiguous. E.g. <code>String.format</code>, <code>ByteBufferUtil.bytes</code>, <code>Iterables.filter/any/transform</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>When naming static methods, select names that maintain semantic legibility when statically imported, and are unlikely to clash with other method names that may be mixed in the same context.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="imports"><a class="anchor" href="#imports"></a>Imports</h4> |
| <div class="paragraph"> |
| <p>Observe the following order for your imports:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">java |
| [blank line] |
| com.google.common |
| org.apache.commons |
| org.junit |
| org.slf4j |
| [blank line] |
| everything else alphabetically</code></pre> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="format-files-for-ides"><a class="anchor" href="#format-files-for-ides"></a>Format files for IDEs</h3> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>IntelliJ: |
| <a href="https://wiki.apache.org/cassandra/CodeStyle?action=AttachFile&do=view&target=intellij-codestyle.jar">intellij-codestyle.jar</a></p> |
| </li> |
| <li> |
| <p>IntelliJ 13: |
| <a href="https://gist.github.com/jdsumsion/9ab750a05c2a567c6afc">gist for IntelliJ |
| 13</a> (this is a work in progress, still working on javadoc, ternary |
| style, line continuations, etc)</p> |
| </li> |
| <li> |
| <p>Eclipse: (<a href="https://github.com/tjake/cassandra-style-eclipse" class="bare">github.com/tjake/cassandra-style-eclipse</a>)</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| <footer class="grad grad--two flex-center pb-xlarge"> |
| <div class="inner text-center z2 relative"> |
| <h2 class="white py-small">Get started with Cassandra, fast.</h2> |
| <a id="footer-cta" href="/_/quickstart.html" class="btn btn--filled ma-medium">Quickstart Guide</a> |
| </div> |
| <div class="inner flex flex-distribute-items mt-xlarge z2 relative"> |
| <div class="col-2"> |
| <div id="footer-logo" class="logo logo--footer mb-medium"><img src="../../assets/img/logo-white-r.png" alt="Cassandra Logo"></div> |
| <p>Apache Cassandra<img src="../../assets/img/registered.svg" alt="®" style="width:18px;"> powers mission-critical deployments with improved performance and unparalleled levels of scale in the cloud.</p> |
| <div class="footer-social-icons"> |
| <a href="https://twitter.com/cassandra?lang=en" target="_blank"><img src="../../assets/img/twitter-icon-circle-white.svg" alt="twitter icon" width="24"></a> |
| <a href="https://www.linkedin.com/company/apache-cassandra/" target="_blank"><img src="../../assets/img/LI-In-Bug.png" alt="linked-in icon" width="24"></a> |
| <a href="https://www.youtube.com/c/PlanetCassandra" target="_blank"><img src="../../assets/img/youtube-icon.png" alt="youtube icon" width="24"></a> |
| </div> |
| </div> |
| <div class="col-2 flex flex-center"> |
| <ul class="columns-2"> |
| <li class="mb-small"><a href="/">Home</a></li> |
| <li class="mb-small"><a href="/_/cassandra-basics.html">Cassandra Basics</a></li> |
| <li class="mb-small"><a href="/_/quickstart.html">Quickstart</a></li> |
| <li class="mb-small"><a href="/_/ecosystem.html">Ecosystem</a></li> |
| <li class="mb-small"><a href="/doc/latest/">Documentation</a></li> |
| <li class="mb-small"><a href="/_/community.html">Community</a></li> |
| <li class="mb-small"><a href="/_/case-studies.html">Case Studies</a></li> |
| <li class="mb-small"><a href="/_/resources.html">Resources</a></li> |
| <li class="mb-small"><a href="/_/blog.html">Blog</a></li> |
| </ul> |
| </div> |
| </div> |
| </footer> |
| <div class="lower-footer bg-white pa-medium"> |
| <div class="flex flex-row flex-vert-center"> |
| <div class="pr-medium"><img src="../../assets/img//feather-small.png" alt="ASF" width="20"></div> |
| <div class="pr-medium"><a href="http://www.apache.org/" target="_blank">Foundation</a></div> |
| <div class="pr-medium"><a href="https://www.apache.org/events/current-event.html" target="_blank">Events</a></div> |
| <div class="pr-medium"><a href="https://www.apache.org/licenses/" target="_blank">License</a></div> |
| <div class="pr-medium"><a href="https://www.apache.org/foundation/thanks" target="_blank">Thanks</a></div> |
| <div class="pr-medium"><a href="https://www.apache.org/security" target="_blank">Security</a></div> |
| <div class="pr-medium"><a href="https://privacy.apache.org/policies/privacy-policy-public.html" target="_blank">Privacy</a></div> |
| <div class="pr-medium"><a href="https://www.apache.org/foundation/sponsorship" target="_blank">Sponsorship</a></div> |
| </div> |
| <p class="my-medium">© 2009-<script>document.write(new Date().getFullYear())</script> <a href="https://apache.org" target="_blank">The Apache Software Foundation</a> under the terms of the Apache License 2.0. Apache, the Apache feather logo, Apache Cassandra, Cassandra, and the Cassandra logo, are either registered trademarks or trademarks of The Apache Software Foundation.</p> |
| </div> |
| <div id="fade" class="hidden"></div> |
| <div id="modal" class="hidden"> |
| <div id="close-modal" class="cursor-pointer"><svg viewBox="0 0 24 24" width="24" height="24" stroke="currentColor" stroke-width="2" fill="none" stroke-linecap="round" stroke-linejoin="round" class="css-i6dzq1"><line x1="18" y1="6" x2="6" y2="18"></line><line x1="6" y1="6" x2="18" y2="18"></line></svg></div> |
| <div id="mod-content" class="vid-mod-content resp-container"></div> |
| </div> |
| <script> |
| jQuery(function(){ |
| var windowW = $(window).width(); |
| $(document) |
| .on('click','.mobile-nav-icon',function(){ |
| $('.main-nav').fadeIn(); |
| }) |
| .on('click','.main-nav',function(){ |
| if(windowW <= 1000){ |
| $(this).fadeOut(); |
| } |
| }) |
| .on('click','#version-toggle',function(){ |
| $(this).toggleClass('active'); |
| $(this).next().fadeToggle(); |
| }) |
| .on('click','#mobile-docs-nav-burger', function(){ |
| $(this).toggleClass('active'); |
| $('.docs-nav').toggleClass('active'); |
| }); |
| var url = window.location.pathname; |
| var isQuickstart = url.includes('quickstart.html'); |
| if(isQuickstart){ |
| var footerCTA = document.getElementById('footer-cta'); |
| footerCTA.innerHTML = 'Get latest updates'; |
| footerCTA.setAttribute('href', '/_/blog.html'); |
| } |
| }); |
| </script> |
| </div> |
| </body> |
| <script> |
| jQuery(function(){ |
| jQuery(document) |
| .on('click','.cassandra-cloud h3',function(){ |
| var el = jQuery(this); |
| el.toggleClass('active'); |
| el.next().slideToggle(); |
| }) |
| .on('click','.image-expand img', function(){ |
| $(this).clone().appendTo('#mod-content'); |
| $('#fade,#modal,#close-modal').fadeIn(); |
| $('body,html').addClass('no-scroll'); |
| }) |
| .on('click','#fade,#close-modal', function(){ |
| $('#fade,#modal,#close-modal').fadeOut(); |
| $('body,html').removeClass('no-scroll'); |
| $('#mod-content').html(''); |
| }); |
| }); |
| </script> |
| </html> |
