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 2f8ce2f [FLINK-13812][code style][zh] Usage of Java Optional
2f8ce2f is described below
commit 2f8ce2ff9d3d471a8440e466ce12e52a770ecce3
Author: Andrey Zagrebin <azagre...@gmail.com>
AuthorDate: Wed Aug 28 11:46:17 2019 +0200
[FLINK-13812][code style][zh] Usage of Java Optional
---
contributing/code-style-and-quality-common.zh.md | 2 +-
contributing/code-style-and-quality-java.zh.md | 11 +++++++++++
2 files changed, 12 insertions(+), 1 deletion(-)
diff --git a/contributing/code-style-and-quality-common.zh.md
b/contributing/code-style-and-quality-common.zh.md
index a8643a9..82caabf 100644
--- a/contributing/code-style-and-quality-common.zh.md
+++ b/contributing/code-style-and-quality-common.zh.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.zh.md
b/contributing/code-style-and-quality-java.zh.md
index f0de4e7..d5af274 100644
--- a/contributing/code-style-and-quality-java.zh.md
+++ b/contributing/code-style-and-quality-java.zh.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.
