You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@flink.apache.org by ch...@apache.org on 2017/07/12 14:30:35 UTC
flink-web git commit: [FLINK-6835] Update code style documentation
Repository: flink-web
Updated Branches:
refs/heads/asf-site c6c564165 -> 13fc61c2e
[FLINK-6835] Update code style documentation
Project: http://git-wip-us.apache.org/repos/asf/flink-web/repo
Commit: http://git-wip-us.apache.org/repos/asf/flink-web/commit/13fc61c2
Tree: http://git-wip-us.apache.org/repos/asf/flink-web/tree/13fc61c2
Diff: http://git-wip-us.apache.org/repos/asf/flink-web/diff/13fc61c2
Branch: refs/heads/asf-site
Commit: 13fc61c2e850c3ca23904f2e7eba2091f2b83f75
Parents: c6c5641
Author: zentol <ch...@apache.org>
Authored: Fri Jun 2 17:21:42 2017 +0200
Committer: zentol <ch...@apache.org>
Committed: Wed Jul 12 16:29:42 2017 +0200
----------------------------------------------------------------------
content/contribute-code.html | 97 +++++++++++++++++++++++++++++++++------
contribute-code.md | 65 +++++++++++++++++++++-----
2 files changed, 136 insertions(+), 26 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/flink-web/blob/13fc61c2/content/contribute-code.html
----------------------------------------------------------------------
diff --git a/content/contribute-code.html b/content/contribute-code.html
index 81dde9f..7421ebd 100644
--- a/content/contribute-code.html
+++ b/content/contribute-code.html
@@ -153,7 +153,18 @@
</ul>
</li>
<li><a href="#coding-guidelines" id="markdown-toc-coding-guidelines">Coding guidelines</a></li>
- <li><a href="#code-style" id="markdown-toc-code-style">Code style</a></li>
+ <li><a href="#code-style" id="markdown-toc-code-style">Code style</a> <ul>
+ <li><a href="#license" id="markdown-toc-license">License</a></li>
+ <li><a href="#imports" id="markdown-toc-imports">Imports</a></li>
+ <li><a href="#naming" id="markdown-toc-naming">Naming</a></li>
+ <li><a href="#whitespace" id="markdown-toc-whitespace">Whitespace</a></li>
+ <li><a href="#braces" id="markdown-toc-braces">Braces</a></li>
+ <li><a href="#javadocs" id="markdown-toc-javadocs">Javadocs</a></li>
+ <li><a href="#modifiers" id="markdown-toc-modifiers">Modifiers</a></li>
+ <li><a href="#files" id="markdown-toc-files">Files</a></li>
+ <li><a href="#misc" id="markdown-toc-misc">Misc</a></li>
+ </ul>
+ </li>
<li><a href="#best-practices" id="markdown-toc-best-practices">Best practices</a></li>
<li><a href="#setup-a-development-environment" id="markdown-toc-setup-a-development-environment">Setup a development environment</a> <ul>
<li><a href="#requirements-for-developing-and-building-flink" id="markdown-toc-requirements-for-developing-and-building-flink">Requirements for developing and building Flink</a></li>
@@ -307,24 +318,82 @@
<h2 id="code-style">Code style</h2>
+<h3 id="license">License</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>
- <li><strong>Tabs vs. spaces</strong>. We are using tabs for indentation, not spaces. We are not religious there, it just happened to be that we started with tabs, and it is important to not mix them (merge/diff conflicts).</li>
- <li>
- <p><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):</p>
+ <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</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><imports from org.apache.flink.*></li>
+ <li><imports from other libraries></li>
+ <li><imports from javax.*></li>
+ <li><imports from java.*></li>
+ <li><imports from scala.*></li>
+ <li><static imports></li>
+ </ul>
+ </li>
+</ul>
+
+<h3 id="naming">Naming</h3>
+<ul>
+ <li><strong>Package names must start with a letter, and must not contain upper-case letters or special characters.</strong></li>
+ <li><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 camcel case.</strong> (<code>myNonStaticField</code>)</li>
+</ul>
+
+<h3 id="whitespace">Whitespace</h3>
+<ul>
+ <li><strong>Tabs vs. spaces.</strong> We are using tabs for indentation, not spaces. We are not religious there, it just happened to be that we started with tabs, and it is important to not mix them (merge/diff conflicts).</li>
+ <li><strong>No trailing whitespace.</strong></li>
+ <li><strong>Spaces around operators/keywords.</strong> Operators (+, =, >, …) and keywords (if, for, catch, …) must have a space before and after them, provided they are not at the start or end of the line.</li>
+</ul>
- <div class="highlight"><pre><code class="language-java"><span class="k">for</span> <span class="o">(...)</span> <span class="o">{</span>
+<h3 id="braces">Braces</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):
+If you are wondering why, recall the famous <a href="https://www.imperialviolet.org/2014/02/22/applebug.html"><em>goto bug</em></a> in Apple’s SSL library.</li>
+</ul>
+
+<div class="highlight"><pre><code class="language-java"><span class="k">for</span> <span class="o">(...)</span> <span class="o">{</span>
<span class="o">...</span>
<span class="o">}</span></code></pre></div>
- <p>If you are wondering why, recall the famous <a href="https://www.imperialviolet.org/2014/02/22/applebug.html"><em>goto bug</em></a> in Apple’s SSL library.</p>
- </li>
- <li><strong>No wildcard imports</strong>. Do not use wildcard imports in the core files. They can cause problems when adding to the code and in some cases even during refactoring. Exceptions are the Tuple classes, Tuple-related utilities, and Flink user programs, when importing operators/functions. Tests are a special case of the user programs.</li>
- <li><strong>No unused imports</strong>. Remove all unused imports.</li>
- <li><strong>Use Guava Checks</strong>. To increase homogeneity, consistently use Guava methods checkNotNull and checkArgument rather than Apache Commons Validate.</li>
- <li><strong>No raw generic types</strong>. Do not use raw generic types, unless strictly necessary (sometime necessary for signature matches, arrays).</li>
- <li><strong>Supress warnings</strong>. Add annotations to suppress warnings, if they cannot be avoided (such as “unchecked”, or “serial”).</li>
+
+<h3 id="javadocs">Javadocs</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</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</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</h3>
+<ul>
+ <li><strong>Arrays must be defined Java-style.</strong> I.e <code>public String[] array</code>.</li>
+ <li><strong>Use Flink Preconditions.</strong> To increase homogeneity, consistently use org.apache.flink.Preconditons methods checkNotNull and checkArgument rather than Apache Commons Validate or Google Guava.</li>
+ <li><strong>No raw generic types.</strong> Do not use raw generic types, unless strictly necessary (sometime necessary for signature matches, arrays).</li>
+ <li><strong>Supress warnings.</strong> Add annotations to suppress warnings, if they cannot be avoided (such as “unchecked”, or “serial”).</li>
<li>
- <p><strong>Comments</strong>. Add comments to your code. What is it doing? Add JavaDocs or inherit them by not adding any comments to the methods. Do not automatically generate comments and avoid unnecessary comments like:</p>
+ <p><strong>Comments.</strong> Add comments to your code. What is it doing? Add JavaDocs or inherit them by not adding any comments to the methods. Do not automatically generate comments and avoid unnecessary comments like:</p>
<div class="highlight"><pre><code class="language-java"><span class="n">i</span><span class="o">++;</span> <span class="c1">// increment by one</span></code></pre></div>
</li>
http://git-wip-us.apache.org/repos/asf/flink-web/blob/13fc61c2/contribute-code.md
----------------------------------------------------------------------
diff --git a/contribute-code.md b/contribute-code.md
index 0267915..bef6c1d 100755
--- a/contribute-code.md
+++ b/contribute-code.md
@@ -137,22 +137,63 @@ It is also possible to attach a patch to a [JIRA]({{site.FLINK_ISSUES_URL}}) iss
## Code style
-- **Apache license headers**. Make sure you have Apache License headers in your files. The RAT plugin is checking for that when you build the code.
-- **Tabs vs. spaces**. We are using tabs for indentation, not spaces. We are not religious there, it just happened to be that we started with tabs, and it is important to not mix them (merge/diff conflicts).
-- **Blocks**. All statements after `if`, `for`, `while`, `do`, ... must always be encapsulated in a block with curly braces (even if the block contains one statement):
-
- ```java
+### License
+- **Apache license headers.** Make sure you have Apache License headers in your files. The RAT plugin is checking for that when you build the code.
+
+### Imports
+- **Empty line before and after package declaration.**
+- **No unused imports.**
+- **No redundant imports.**
+- **No wildcard imports.** They can cause problems when adding to the code and in some cases even during refactoring.
+- **Import order.** Imports must be ordered alphabetically, grouped into the following blocks, with each block separated by an empty line:
+ - <imports from org.apache.flink.*>
+ - <imports from other libraries>
+ - <imports from javax.*>
+ - <imports from java.*>
+ - <imports from scala.*>
+ - <static imports>
+
+### Naming
+- **Package names must start with a letter, and must not contain upper-case letters or special characters.**
+- **Non-private static final fields must be upper-case, with words being separated by underscores.** (`MY_STATIC_VARIABLE`)
+- **Non-static fields/methods must be in lower camcel case.** (`myNonStaticField`)
+
+### Whitespace
+- **Tabs vs. spaces.** We are using tabs for indentation, not spaces. We are not religious there, it just happened to be that we started with tabs, and it is important to not mix them (merge/diff conflicts).
+- **No trailing whitespace.**
+- **Spaces around operators/keywords.** Operators (+, =, >, ...) and keywords (if, for, catch, ...) must have a space before and after them, provided they are not at the start or end of the line.
+
+### Braces
+- **Left curly braces (`{`) must not be placed on a new line.**
+- **Right curly braces (`}`) must always be placed at the beginning of the line.**
+- **Blocks.** All statements after `if`, `for`, `while`, `do`, ... must always be encapsulated in a block with curly braces (even if the block contains one statement):
+ If you are wondering why, recall the famous [*goto bug*](https://www.imperialviolet.org/2014/02/22/applebug.html) in Apple's SSL library.
+
+```java
for (...) {
...
}
```
- If you are wondering why, recall the famous [*goto bug*](https://www.imperialviolet.org/2014/02/22/applebug.html) in Apple's SSL library.
-- **No wildcard imports**. Do not use wildcard imports in the core files. They can cause problems when adding to the code and in some cases even during refactoring. Exceptions are the Tuple classes, Tuple-related utilities, and Flink user programs, when importing operators/functions. Tests are a special case of the user programs.
-- **No unused imports**. Remove all unused imports.
-- **Use Guava Checks**. To increase homogeneity, consistently use Guava methods checkNotNull and checkArgument rather than Apache Commons Validate.
-- **No raw generic types**. Do not use raw generic types, unless strictly necessary (sometime necessary for signature matches, arrays).
-- **Supress warnings**. Add annotations to suppress warnings, if they cannot be avoided (such as "unchecked", or "serial").
-- **Comments**. Add comments to your code. What is it doing? Add JavaDocs or inherit them by not adding any comments to the methods. Do not automatically generate comments and avoid unnecessary comments like:
+
+### Javadocs
+- **All public/protected methods and classes must have a Javadoc.**
+- **The first sentence of the javadoc must end with a period.**
+- **Paragraphs must be separated with a new line, and started with <p>.**
+
+### Modifiers
+- **No redundant modifiers.** For example, public modifiers in interface methods.
+- **Follow JLS3 modifier order.** Modifiers must be ordered in the following order: public, protected, private, abstract, static, final, transient, volatile, synchronized, native, strictfp.
+
+### Files
+- **All files must end with `\n`.**
+- **File length must not exceed 3000 lines.**
+
+### Misc
+- **Arrays must be defined Java-style.** I.e `public String[] array`.
+- **Use Flink Preconditions.** To increase homogeneity, consistently use org.apache.flink.Preconditons methods checkNotNull and checkArgument rather than Apache Commons Validate or Google Guava.
+- **No raw generic types.** Do not use raw generic types, unless strictly necessary (sometime necessary for signature matches, arrays).
+- **Supress warnings.** Add annotations to suppress warnings, if they cannot be avoided (such as "unchecked", or "serial").
+- **Comments.** Add comments to your code. What is it doing? Add JavaDocs or inherit them by not adding any comments to the methods. Do not automatically generate comments and avoid unnecessary comments like:
```java
i++; // increment by one