blob: f514791aa7efd61c040274901590299f1101fe86 [file] [log] [blame]
<!DOCTYPE html>
<html lang="en" dir=ZgotmplZ>
<head>
<link rel="stylesheet" href="/bootstrap/css/bootstrap.min.css">
<script src="/bootstrap/js/bootstrap.bundle.min.js"></script>
<link rel="stylesheet" type="text/css" href="/font-awesome/css/font-awesome.min.css">
<script src="/js/anchor.min.js"></script>
<script src="/js/flink.js"></script>
<link rel="canonical" href="https://flink.apache.org/how-to-contribute/code-style-and-quality-formatting/">
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="Code Style and Quality Guide — Formatting Guide # Preamble # Pull Requests &amp; Changes # Common Coding Guide # Java Language Guide # Scala Language Guide # Components Guide # Formatting Guide # Java Code Formatting Style # We recommend to set up the IDE to automatically check the code style. Please follow the IDE Setup Guide to set up spotless and checkstyle .
License # Apache license headers.">
<meta name="theme-color" content="#FFFFFF"><meta property="og:title" content="Code Style and Quality Guide — Formatting Guide" />
<meta property="og:description" content="Code Style and Quality Guide — Formatting Guide # Preamble # Pull Requests &amp; Changes # Common Coding Guide # Java Language Guide # Scala Language Guide # Components Guide # Formatting Guide # Java Code Formatting Style # We recommend to set up the IDE to automatically check the code style. Please follow the IDE Setup Guide to set up spotless and checkstyle .
License # Apache license headers." />
<meta property="og:type" content="article" />
<meta property="og:url" content="https://flink.apache.org/how-to-contribute/code-style-and-quality-formatting/" /><meta property="article:section" content="how-to-contribute" />
<title>Code Style and Quality Guide — Formatting Guide | Apache Flink</title>
<link rel="manifest" href="/manifest.json">
<link rel="icon" href="/favicon.png" type="image/x-icon">
<link rel="alternate" hreflang="zh" href="https://flink.apache.org/zh/how-to-contribute/code-style-and-quality-formatting/" title="Code Style and Quality Guide — Formatting Guide">
<link rel="stylesheet" href="/book.min.22eceb4d17baa9cdc0f57345edd6f215a40474022dfee39b63befb5fb3c596b5.css" integrity="sha256-IuzrTRe6qc3A9XNF7dbyFaQEdAIt/uObY777X7PFlrU=">
<script defer src="/en.search.min.2698f0d1b683dae4d6cb071668b310a55ebcf1c48d11410a015a51d90105b53e.js" integrity="sha256-Jpjw0baD2uTWywcWaLMQpV688cSNEUEKAVpR2QEFtT4="></script>
<!--
Made with Book Theme
https://github.com/alex-shpak/hugo-book
-->
<meta name="generator" content="Hugo 0.124.1">
<script>
var _paq = window._paq = window._paq || [];
_paq.push(['disableCookies']);
_paq.push(["setDomains", ["*.flink.apache.org","*.nightlies.apache.org/flink"]]);
_paq.push(['trackPageView']);
_paq.push(['enableLinkTracking']);
(function() {
var u="//analytics.apache.org/";
_paq.push(['setTrackerUrl', u+'matomo.php']);
_paq.push(['setSiteId', '1']);
var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
g.async=true; g.src=u+'matomo.js'; s.parentNode.insertBefore(g,s);
})();
</script>
</head>
<body dir=ZgotmplZ>
<header>
<nav class="navbar navbar-expand-xl">
<div class="container-fluid">
<a class="navbar-brand" href="/">
<img src="/img/logo/png/100/flink_squirrel_100_color.png" alt="Apache Flink" height="47" width="47" class="d-inline-block align-text-middle">
<span>Apache Flink</span>
</a>
<button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarSupportedContent" aria-controls="navbarSupportedContent" aria-expanded="false" aria-label="Toggle navigation">
<i class="fa fa-bars navbar-toggler-icon"></i>
</button>
<div class="collapse navbar-collapse" id="navbarSupportedContent">
<ul class="navbar-nav">
<li class="nav-item dropdown">
<a class="nav-link dropdown-toggle" href="#" role="button" data-bs-toggle="dropdown" aria-expanded="false">About</a>
<ul class="dropdown-menu">
<li>
<a class="dropdown-item" href="/what-is-flink/flink-architecture/">Architecture</a>
</li>
<li>
<a class="dropdown-item" href="/what-is-flink/flink-applications/">Applications</a>
</li>
<li>
<a class="dropdown-item" href="/what-is-flink/flink-operations/">Operations</a>
</li>
<li>
<a class="dropdown-item" href="/what-is-flink/use-cases/">Use Cases</a>
</li>
<li>
<a class="dropdown-item" href="/what-is-flink/powered-by/">Powered By</a>
</li>
<li>
<a class="dropdown-item" href="/what-is-flink/roadmap/">Roadmap</a>
</li>
<li>
<a class="dropdown-item" href="/what-is-flink/community/">Community & Project Info</a>
</li>
<li>
<a class="dropdown-item" href="/what-is-flink/security/">Security</a>
</li>
<li>
<a class="dropdown-item" href="/what-is-flink/special-thanks/">Special Thanks</a>
</li>
</ul>
</li>
<li class="nav-item dropdown">
<a class="nav-link dropdown-toggle" href="#" role="button" data-bs-toggle="dropdown" aria-expanded="false">Getting Started</a>
<ul class="dropdown-menu">
<li>
<a class="dropdown-item" href="https://nightlies.apache.org/flink/flink-docs-stable/docs/try-flink/local_installation/">With Flink<i class="link fa fa-external-link title" aria-hidden="true"></i>
</a>
</li>
<li>
<a class="dropdown-item" href="https://nightlies.apache.org/flink/flink-kubernetes-operator-docs-stable/docs/try-flink-kubernetes-operator/quick-start/">With Flink Kubernetes Operator<i class="link fa fa-external-link title" aria-hidden="true"></i>
</a>
</li>
<li>
<a class="dropdown-item" href="https://nightlies.apache.org/flink/flink-cdc-docs-stable/docs/get-started/introduction/">With Flink CDC<i class="link fa fa-external-link title" aria-hidden="true"></i>
</a>
</li>
<li>
<a class="dropdown-item" href="https://nightlies.apache.org/flink/flink-ml-docs-stable/docs/try-flink-ml/quick-start/">With Flink ML<i class="link fa fa-external-link title" aria-hidden="true"></i>
</a>
</li>
<li>
<a class="dropdown-item" href="https://nightlies.apache.org/flink/flink-statefun-docs-stable/getting-started/project-setup.html">With Flink Stateful Functions<i class="link fa fa-external-link title" aria-hidden="true"></i>
</a>
</li>
<li>
<a class="dropdown-item" href="https://nightlies.apache.org/flink/flink-docs-stable/docs/learn-flink/overview/">Training Course<i class="link fa fa-external-link title" aria-hidden="true"></i>
</a>
</li>
</ul>
</li>
<li class="nav-item dropdown">
<a class="nav-link dropdown-toggle" href="#" role="button" data-bs-toggle="dropdown" aria-expanded="false">Documentation</a>
<ul class="dropdown-menu">
<li>
<a class="dropdown-item" href="https://nightlies.apache.org/flink/flink-docs-stable/">Flink 1.19 (stable)<i class="link fa fa-external-link title" aria-hidden="true"></i>
</a>
</li>
<li>
<a class="dropdown-item" href="https://nightlies.apache.org/flink/flink-docs-master/">Flink Master (snapshot)<i class="link fa fa-external-link title" aria-hidden="true"></i>
</a>
</li>
<li>
<a class="dropdown-item" href="https://nightlies.apache.org/flink/flink-kubernetes-operator-docs-stable/">Kubernetes Operator 1.8 (latest)<i class="link fa fa-external-link title" aria-hidden="true"></i>
</a>
</li>
<li>
<a class="dropdown-item" href="https://nightlies.apache.org/flink/flink-kubernetes-operator-docs-main">Kubernetes Operator Main (snapshot)<i class="link fa fa-external-link title" aria-hidden="true"></i>
</a>
</li>
<li>
<a class="dropdown-item" href="https://nightlies.apache.org/flink/flink-cdc-docs-stable">CDC 3.0 (stable)<i class="link fa fa-external-link title" aria-hidden="true"></i>
</a>
</li>
<li>
<a class="dropdown-item" href="https://nightlies.apache.org/flink/flink-cdc-docs-master">CDC Master (snapshot)<i class="link fa fa-external-link title" aria-hidden="true"></i>
</a>
</li>
<li>
<a class="dropdown-item" href="https://nightlies.apache.org/flink/flink-ml-docs-stable/">ML 2.3 (stable)<i class="link fa fa-external-link title" aria-hidden="true"></i>
</a>
</li>
<li>
<a class="dropdown-item" href="https://nightlies.apache.org/flink/flink-ml-docs-master">ML Master (snapshot)<i class="link fa fa-external-link title" aria-hidden="true"></i>
</a>
</li>
<li>
<a class="dropdown-item" href="https://nightlies.apache.org/flink/flink-statefun-docs-stable/">Stateful Functions 3.3 (stable)<i class="link fa fa-external-link title" aria-hidden="true"></i>
</a>
</li>
<li>
<a class="dropdown-item" href="https://nightlies.apache.org/flink/flink-statefun-docs-master">Stateful Functions Master (snapshot)<i class="link fa fa-external-link title" aria-hidden="true"></i>
</a>
</li>
</ul>
</li>
<li class="nav-item dropdown">
<a class="nav-link dropdown-toggle" href="#" role="button" data-bs-toggle="dropdown" aria-expanded="false">How to Contribute</a>
<ul class="dropdown-menu">
<li>
<a class="dropdown-item" href="/how-to-contribute/overview/">Overview</a>
</li>
<li>
<a class="dropdown-item" href="/how-to-contribute/contribute-code/">Contribute Code</a>
</li>
<li>
<a class="dropdown-item" href="/how-to-contribute/reviewing-prs/">Review Pull Requests</a>
</li>
<li>
<a class="dropdown-item" href="/how-to-contribute/code-style-and-quality-preamble/">Code Style and Quality Guide</a>
</li>
<li>
<a class="dropdown-item" href="/how-to-contribute/contribute-documentation/">Contribute Documentation</a>
</li>
<li>
<a class="dropdown-item" href="/how-to-contribute/documentation-style-guide/">Documentation Style Guide</a>
</li>
<li>
<a class="dropdown-item" href="/how-to-contribute/improve-website/">Contribute to the Website</a>
</li>
<li>
<a class="dropdown-item" href="/how-to-contribute/getting-help/">Getting Help</a>
</li>
</ul>
</li>
<li class="nav-item">
<a class="nav-link" href="/posts/">Flink Blog</a>
</li>
<li class="nav-item">
<a class="nav-link" href="/downloads/">Downloads</a>
</li>
</ul>
<div class="book-search">
<div class="book-search-spinner hidden">
<i class="fa fa-refresh fa-spin"></i>
</div>
<form class="search-bar d-flex" onsubmit="return false;"su>
<input type="text" id="book-search-input" placeholder="Search" aria-label="Search" maxlength="64" data-hotkeys="s/">
<i class="fa fa-search search"></i>
<i class="fa fa-circle-o-notch fa-spin spinner"></i>
</form>
<div class="book-search-spinner hidden"></div>
<ul id="book-search-results"></ul>
</div>
</div>
</div>
</nav>
<div class="navbar-clearfix"></div>
</header>
<main class="flex">
<section class="container book-page">
<article class="markdown"><h1 id="code-style-and-quality-guide--formatting-guide">
Code Style and Quality Guide — Formatting Guide
<a class="anchor" href="#code-style-and-quality-guide--formatting-guide">#</a>
</h1>
<h4 id="preamblehahahugoshortcode59s0hbhb">
<a href="/how-to-contribute/code-style-and-quality-preamble/">Preamble</a>
<a class="anchor" href="#preamblehahahugoshortcode59s0hbhb">#</a>
</h4>
<h4 id="pull-requests--changeshahahugoshortcode59s1hbhb">
<a href="/how-to-contribute/code-style-and-quality-pull-requests/">Pull Requests &amp; Changes</a>
<a class="anchor" href="#pull-requests--changeshahahugoshortcode59s1hbhb">#</a>
</h4>
<h4 id="common-coding-guidehahahugoshortcode59s2hbhb">
<a href="/how-to-contribute/code-style-and-quality-common/">Common Coding Guide</a>
<a class="anchor" href="#common-coding-guidehahahugoshortcode59s2hbhb">#</a>
</h4>
<h4 id="java-language-guidehahahugoshortcode59s3hbhb">
<a href="/how-to-contribute/code-style-and-quality-java/">Java Language Guide</a>
<a class="anchor" href="#java-language-guidehahahugoshortcode59s3hbhb">#</a>
</h4>
<h4 id="scala-language-guidehahahugoshortcode59s4hbhb">
<a href="/how-to-contribute/code-style-and-quality-scala/">Scala Language Guide</a>
<a class="anchor" href="#scala-language-guidehahahugoshortcode59s4hbhb">#</a>
</h4>
<h4 id="components-guidehahahugoshortcode59s5hbhb">
<a href="/how-to-contribute/code-style-and-quality-components/">Components Guide</a>
<a class="anchor" href="#components-guidehahahugoshortcode59s5hbhb">#</a>
</h4>
<h4 id="formatting-guidehahahugoshortcode59s6hbhb">
<a href="/how-to-contribute/code-style-and-quality-formatting/">Formatting Guide</a>
<a class="anchor" href="#formatting-guidehahahugoshortcode59s6hbhb">#</a>
</h4>
<h2 id="java-code-formatting-style">
Java Code Formatting Style
<a class="anchor" href="#java-code-formatting-style">#</a>
</h2>
<p>We recommend to set up the IDE to automatically check the code style. Please follow the
<a href="//nightlies.apache.org/flink/flink-docs-stable/docs/flinkdev/ide_setup/">
IDE Setup Guide
</a>
to set up
<a href="//nightlies.apache.org/flink/flink-docs-stable/docs/flinkdev/ide_setup/#code-formatting">
spotless
</a>
and
<a href="//nightlies.apache.org/flink/flink-docs-stable/docs/flinkdev/ide_setup/#checkstyle-for-java">
checkstyle
</a>
.</p>
<h3 id="license">
License
<a class="anchor" href="#license">#</a>
</h3>
<ul>
<li><strong>Apache license headers.</strong> Make sure you have Apache License headers in your files. The RAT plugin is checking for that when you build the code.</li>
</ul>
<h3 id="imports">
Imports
<a class="anchor" href="#imports">#</a>
</h3>
<ul>
<li><strong>Empty line before and after package declaration.</strong></li>
<li><strong>No unused imports.</strong></li>
<li><strong>No redundant imports.</strong></li>
<li><strong>No wildcard imports.</strong> They can cause problems when adding to the code and in some cases even during refactoring.</li>
<li><strong>Import order.</strong> Imports must be ordered alphabetically, grouped into the following blocks, with each block separated by an empty line:
<ul>
<li>&lt;imports from org.apache.flink.*&gt;</li>
<li>&lt;imports from org.apache.flink.shaded.*&gt;</li>
<li>&lt;imports from other libraries&gt;</li>
<li>&lt;imports from javax.*&gt;</li>
<li>&lt;imports from java.*&gt;</li>
<li>&lt;imports from scala.*&gt;</li>
<li>&lt;static imports&gt;</li>
</ul>
</li>
</ul>
<h3 id="naming">
Naming
<a class="anchor" href="#naming">#</a>
</h3>
<ul>
<li><strong>Package names must start with a letter, and must not contain upper-case letters or special characters.</strong>
<strong>Non-private static final fields must be upper-case, with words being separated by underscores.</strong>(<code>MY_STATIC_VARIABLE</code>)</li>
<li><strong>Non-static fields/methods must be in lower camel case.</strong> (<code>myNonStaticField</code>)</li>
</ul>
<h3 id="whitespaces">
Whitespaces
<a class="anchor" href="#whitespaces">#</a>
</h3>
<ul>
<li><strong>Tabs vs. spaces.</strong> We are using spaces for indentation, not tabs.</li>
<li><strong>No trailing whitespace.</strong></li>
<li><strong>Spaces around operators/keywords.</strong> Operators (<code>+</code>, <code>=</code>, <code>&gt;</code>, …) and keywords (<code>if</code>, <code>for</code>, <code>catch</code>, …) must have a space before and after them, provided they are not at the start or end of the line.</li>
</ul>
<h3 id="breaking-the-lines-of-too-long-statements">
Breaking the lines of too long statements
<a class="anchor" href="#breaking-the-lines-of-too-long-statements">#</a>
</h3>
<p>In general long lines should be avoided for the better readability. Try to use short statements which operate on the same level of abstraction. Break the long statements by creating more local variables, defining helper functions etc.</p>
<p>Two major sources of long lines are:</p>
<ul>
<li><strong>Long list of arguments</strong> in function declaration or call: <code>void func(type1 arg1, type2 arg2, ...)</code></li>
<li><strong>Long sequence of chained calls</strong>: <code>list.stream().map(...).reduce(...).collect(...)...</code></li>
</ul>
<p>Rules about breaking the long lines:</p>
<ul>
<li>Break the argument list or chain of calls if the line exceeds limit or earlier if you believe that the breaking would improve the code readability</li>
<li>If you break the line then each argument/call should have a separate line, including the first one</li>
<li>Each new line should have one extra indentation (or two for a function declaration) relative to the line of the parent function name or the called entity</li>
</ul>
<p>Additionally for function arguments:</p>
<ul>
<li>The opening parenthesis always stays on the line of the parent function name</li>
<li>The possible thrown exception list is never broken and stays on the same last line, even if the line length exceeds its limit</li>
<li>The line of the function argument should end with a comma staying on the same line except the last argument</li>
</ul>
<p>Example of breaking the list of function arguments:</p>
<pre tabindex="0"><code>public void func(
int arg1,
int arg2,
...) throws E1, E2, E3 {
}
</code></pre><p>The dot of a chained call is always on the line of that chained call proceeding the call at the beginning.</p>
<p>Example of breaking the list of chained calls:</p>
<pre tabindex="0"><code>values
.stream()
.map(...)
.collect(...);
</code></pre><h3 id="braces">
Braces
<a class="anchor" href="#braces">#</a>
</h3>
<ul>
<li><strong>Left curly braces (<code>{</code>) must not be placed on a new line.</strong></li>
<li><strong>Right curly braces (<code>}</code>) must always be placed at the beginning of the line.</strong></li>
<li><strong>Blocks.</strong> All statements after <code>if</code>, <code>for</code>, <code>while</code>, <code>do</code>, … must always be encapsulated in a block with curly braces (even if the block contains one statement).</li>
</ul>
<h3 id="javadocs">
Javadocs
<a class="anchor" href="#javadocs">#</a>
</h3>
<ul>
<li><strong>All public/protected methods and classes must have a Javadoc.</strong></li>
<li><strong>The first sentence of the Javadoc must end with a period.</strong></li>
<li><strong>Paragraphs must be separated with a new line, and started with <p>.</strong></li>
</ul>
<h3 id="modifiers">
Modifiers
<a class="anchor" href="#modifiers">#</a>
</h3>
<ul>
<li><strong>No redundant modifiers.</strong> For example, public modifiers in interface methods.</li>
<li><strong>Follow JLS3 modifier order.</strong> Modifiers must be ordered in the following order: public, protected, private, abstract, static, final, transient, volatile, synchronized, native, strictfp.</li>
</ul>
<h3 id="files">
Files
<a class="anchor" href="#files">#</a>
</h3>
<ul>
<li><strong>All files must end with <code>\n</code>.</strong></li>
<li><strong>File length must not exceed 3000 lines.</strong></li>
</ul>
<h3 id="misc">
Misc
<a class="anchor" href="#misc">#</a>
</h3>
<ul>
<li><strong>Arrays must be defined Java-style.</strong> For example, <code>public String[] array</code>.</li>
<li><strong>Use Flink Preconditions.</strong> To increase homogeneity, consistently use the <code>org.apache.flink.Preconditions</code> methods <code>checkNotNull</code> and <code>checkArgument</code> rather than Apache Commons Validate or Google Guava.</li>
</ul>
</article>
<div class="edit-this-page">
<p>
<a href="https://cwiki.apache.org/confluence/display/FLINK/Flink+Translation+Specifications">Want to contribute translation?</a>
</p>
<p>
<a href="//github.com/apache/flink-web/edit/asf-site/docs/content/how-to-contribute/code-style-and-quality-formatting.md">
Edit This Page<i class="fa fa-edit fa-fw"></i>
</a>
</p>
</div>
</section>
<aside class="book-toc">
<nav id="TableOfContents"><h3>On This Page <a href="javascript:void(0)" class="toc" onclick="collapseToc()"><i class="fa fa-times" aria-hidden="true"></i></a></h3>
<ul>
<li><a href="#code-style-and-quality-guide--formatting-guide">Code Style and Quality Guide — Formatting Guide</a>
<ul>
<li>
<ul>
<li></li>
</ul>
</li>
<li><a href="#java-code-formatting-style">Java Code Formatting Style</a>
<ul>
<li><a href="#license">License</a></li>
<li><a href="#imports">Imports</a></li>
<li><a href="#naming">Naming</a></li>
<li><a href="#whitespaces">Whitespaces</a></li>
<li><a href="#breaking-the-lines-of-too-long-statements">Breaking the lines of too long statements</a></li>
<li><a href="#braces">Braces</a></li>
<li><a href="#javadocs">Javadocs</a></li>
<li><a href="#modifiers">Modifiers</a></li>
<li><a href="#files">Files</a></li>
<li><a href="#misc">Misc</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</nav>
</aside>
<aside class="expand-toc hidden">
<a class="toc" onclick="expandToc()" href="javascript:void(0)">
<i class="fa fa-bars" aria-hidden="true"></i>
</a>
</aside>
</main>
<footer>
<div class="separator"></div>
<div class="panels">
<div class="wrapper">
<div class="panel">
<ul>
<li>
<a href="https://flink-packages.org/">flink-packages.org</a>
</li>
<li>
<a href="https://www.apache.org/">Apache Software Foundation</a>
</li>
<li>
<a href="https://www.apache.org/licenses/">License</a>
</li>
<li>
<a href="/zh/how-to-contribute/code-style-and-quality-formatting/">
<i class="fa fa-globe" aria-hidden="true"></i>&nbsp;中文版
</a>
</li>
</ul>
</div>
<div class="panel">
<ul>
<li>
<a href="/what-is-flink/security">Security</a-->
</li>
<li>
<a href="https://www.apache.org/foundation/sponsorship.html">Donate</a>
</li>
<li>
<a href="https://www.apache.org/foundation/thanks.html">Thanks</a>
</li>
</ul>
</div>
<div class="panel icons">
<div>
<a href="/posts">
<div class="icon flink-blog-icon"></div>
<span>Flink blog</span>
</a>
</div>
<div>
<a href="https://github.com/apache/flink">
<div class="icon flink-github-icon"></div>
<span>Github</span>
</a>
</div>
<div>
<a href="https://twitter.com/apacheflink">
<div class="icon flink-twitter-icon"></div>
<span>Twitter</span>
</a>
</div>
</div>
</div>
</div>
<hr/>
<div class="container disclaimer">
<p>The contents of this website are © 2024 Apache Software Foundation under the terms of the Apache License v2. Apache Flink, Flink, and the Flink logo are either registered trademarks or trademarks of The Apache Software Foundation in the United States and other countries.</p>
</div>
</footer>
</body>
</html>