You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@flink.apache.org by az...@apache.org on 2019/08/28 09:36:34 UTC

[flink-web] branch asf-site updated: [FLINK-13812][code style] Usage of Java Optional

This is an automated email from the ASF dual-hosted git repository.

azagrebin pushed a commit to branch asf-site
in repository https://gitbox.apache.org/repos/asf/flink-web.git


The following commit(s) were added to refs/heads/asf-site by this push:
     new 5088cce  [FLINK-13812][code style] Usage of Java Optional
5088cce is described below

commit 5088cce017c888514567460a7a4cc2b8915127da
Author: Andrey Zagrebin <az...@gmail.com>
AuthorDate: Wed Aug 21 13:17:50 2019 +0200

    [FLINK-13812][code style] Usage of Java Optional
---
 contributing/code-style-and-quality-common.md |  2 +-
 contributing/code-style-and-quality-java.md   | 11 +++++++++++
 2 files changed, 12 insertions(+), 1 deletion(-)

diff --git a/contributing/code-style-and-quality-common.md b/contributing/code-style-and-quality-common.md
index 05f703b..68de3a2 100644
--- a/contributing/code-style-and-quality-common.md
+++ b/contributing/code-style-and-quality-common.md
@@ -140,7 +140,7 @@ That way, you get warnings from IntelliJ about all sections where you have to re
 _Note: This means that `@Nonnull` annotations are usually not necessary, but can be used in certain cases to override a previous annotation, or to point non-nullability out in a context where one would expect a nullable value._
 
 `Optional` is a good solution as a return type for method that may or may not have a result, so nullable return types are good candidates to be replaced with `Optional`. 
-For fields and parameters, `Optional` is disputed in Java and most parts of the Flink code case don’t use optional for fields.
+See also [usage of Java Optional](code-style-and-quality-java.md#java-optional).
 
 
 ### Avoid Code Duplication
diff --git a/contributing/code-style-and-quality-java.md b/contributing/code-style-and-quality-java.md
index e22b2c8..ef7a74c 100644
--- a/contributing/code-style-and-quality-java.md
+++ b/contributing/code-style-and-quality-java.md
@@ -66,6 +66,17 @@ title:  "Apache Flink Code Style and Quality Guide — Java"
 * **Set the initial capacity for a collection only if there is a good proven reason** for that, otherwise do not clutter the code. In case of **Maps** it can be even deluding because the Map's load factor effectively reduces the capacity.
 
 
+### Java Optional
+
+* Use **@Nullable annotation where you do not use Optional** for the nullable values.
+* If you can prove that `Optional` usage would lead to a **performance degradation in critical code then fallback to @Nullable**.
+* Always use **Optional to return nullable values** in the API/public methods except the case of a proven performance concern.
+* **Do not use Optional as a function argument**, instead either overload the method or use the Builder pattern for the set of function arguments.
+     * Note: an Optional argument can be allowed in a private helper method if you believe that it simplifies the code
+     ([example](https://github.com/apache/flink/blob/master/flink-formats/flink-avro/src/main/java/org/apache/flink/formats/avro/typeutils/AvroFactory.java#L95)).
+* **Do not use Optional for class fields**.
+
+
 ### Lambdas
 
 * Prefer non-capturing lambdas (lambdas that do not contain references to the outer scope). Capturing lambdas need to create a new object instance for every call. Non-capturing lambdas can use the same instance for each invocation.