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 <azagre...@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.