klion26 commented on a change in pull request #394: URL: https://github.com/apache/flink-web/pull/394#discussion_r531026701
########## File path: contributing/code-style-and-quality-common.zh.md ########## @@ -30,95 +32,101 @@ Each file must include the Apache license information as a header. */ ``` -## 2. Tools +<a name="tools"></a> + +<a name="tools"></a> -We recommend to follow the [IDE Setup Guide](https://ci.apache.org/projects/flink/flink-docs-master/flinkDev/ide_setup.html#checkstyle-for-java) to get IDE tooling configured. +## 2. 工具 + +我们建议你按照 [IDE 设置指南](https://ci.apache.org/projects/flink/flink-docs-master/flinkDev/ide_setup.html#checkstyle-for-java) 配置 IDE 工具。 <!--- -### Use inspections in IntelliJ +### 在 IntelliJ 中使用检查 -* Import the inspections settings into the IDE (see IDE setup guide) - * TODO: Need to agree on a profile and export it (like checkstyle) -* Write the code such that inspection warnings are addressed - * There are few exceptions where an inspection warning is not meaningful. In that case, suppress the inspection warning. +* 将检查设置导入到 IDE (参阅 IDE 设置指南) + * TODO: 需要同意导出配置文件 (如 checkstyle) +* 编码解决检查警告 + * 当出现没有意义的检查警告时，应该禁止该警告，虽然这种情况很少。 --> -### Warnings +### 警告 + +* 我们争取实现零警告 +* 尽管现有的代码中存在许多警告，但新的修改不应该有任何编译器警告 +* 如果不能用合理的方式处理警告（某些情况下使用泛型时）也应该添加注释以压制警告 +* 弃用方法时，检查是否会引入其他的警告 -* We strive for zero warnings -* Even though there are many warnings in existing code, new changes should not add any additional compiler warnings -* If it is not possible to address the warning in a sane way (in some cases when working with generics) add an annotation to suppress the warning -* When deprecating methods, check that this does not introduce additional warnings +<a name="comments-and-code-readability"></a> -## 3. Comments And Code Readability +## 3. 注释和代码可读性 -### Comments +### 注释 -**Golden rule: Comment as much as necessary to support code understanding, but don’t add redundant information.** +**黄金法则: 尽可能多的注释以支持代码的理解，但不要添加多余的信息。** -Think about +思考 -* <span style="text-decoration:underline;">What</span> is the code doing? -* <span style="text-decoration:underline;">How</span> does the code do this? -* <span style="text-decoration:underline;">Why</span> is the code like that? +* <span style="text-decoration:underline;">What</span> 代码在做什么？ +* <span style="text-decoration:underline;">How</span> 代码怎么做到的？ +* <span style="text-decoration:underline;">Why</span> 代码为什么是这样的？ -The code alone should explain as much as possible the “<span style="text-decoration:underline;">what</span>” and the “<span style="text-decoration:underline;">how</span>” +代码本身应该尽可能的解释 “<span style="text-decoration:underline;">what</span>” 和 “<span style="text-decoration:underline;">how</span>” -* Use JavaDocs to describe the roles of classes and the contracts of methods, in cases where the contract is not obvious or intuitive from the method name (the “what”). -* The flow of the code should give a good description of the “how”. -Think of variable and method names as part of the code documenting itself. -* It often makes reading the code easier if larger blocks that form a unit are moved into a private method with a descriptive name of what that block is doing +* 使用 JavaDocs 来描述类的作用和方法的协议，以防止不能从方法名看出协议（“what”）。 +* 代码流程应该能够很好的描述 “how”。 +将变量和方法名看作是代码文档的一部分。 Review comment: 中文和英文不太一样，中文这里不需要分行，分行渲染之后会觉得比较奇怪 ########## File path: contributing/code-style-and-quality-common.zh.md ########## @@ -30,95 +32,101 @@ Each file must include the Apache license information as a header. */ ``` -## 2. Tools +<a name="tools"></a> + +<a name="tools"></a> Review comment: 这里重复了，添加一个即可 ########## File path: contributing/code-style-and-quality-common.zh.md ########## @@ -137,186 +145,188 @@ the main path ``` -## 4. Design and Structure +<a name="design-and-structure"></a> -While it is hard to exactly specify what constitutes a good design, there are some properties that can serve as a _litmus test_ for a good design. If these properties are given, the chances are good that the design is going into a good direction. If these properties cannot be achieved, there is a high probability that the design is flawed. +## 4. 设计和结构 +虽然很难确切地指定一个好的设计是由什么构成的，但是有一些属性可以作为好的设计的试金石。如果设计上拥有这些属性，那么就有可能得到好的发展。否则，设计就很有可能存在缺陷。 -### Immutability and Eager Initialization -1. Try to use immutable types where possible, especially for APIs, messages, identifiers, properties, configuration, etc. -2. A good general approach is to try and make as many fields of a class `final` as possible. -3. Classes that are used as keys in maps should be strictly immutable and only have `final` fields (except maybe auxiliary fields, like lazy cached hash codes). -4. Eagerly initialize classes. There should be no `init()` or `setup()` methods. Once the constructor completes, the object should be usable. +### 不变性（Immutability）和急切初始化（Eager Initialization） +1. 尽可能尝试使用不可变类型，尤其是 API、消息、标识符、属性、配置等等。 +2. 一个好的通用方法是尽可能地将类中的字段设置为 `final`。 +3. 在 map 中作为 key 的类应该是严格不可变的，并且只有 final 字段（可能除了辅助的字段，如延迟缓存的 key）。 +4. 预初始化类。不应该有 `init()` 或 `setup()` 方法。构造函数完成后，对象应该就可用。 -### Nullability of the Mutable Parts -For nullability, the Flink codebase aims to follow these conventions: +### 可变部件（Mutable Parts）的可空性（Nullability） -* Fields, parameters, and return types are always non-null, unless indicated otherwise -* All fields, parameters and method types that can be null should be annotated with `@javax.annotation.Nullable`. -That way, you get warnings from IntelliJ about all sections where you have to reason about potential null values. -* For all mutable (non-final) fields that are not annotated, the assumption is that while the field value changes, there always is a value. - * This should be double check whether these can in fact not be null throughout the lifetime of the object. +Flink 代码库对于可空性旨在遵循以下约定: -_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._ +* 除非有特殊说明，否则字段、参数和返回类型始终都是非 null。 +* 所有可以为 null 的字段、参数和方法类型都要使用 `@javax.annotation.Nullable` 注解（Annotated）。 +这样 IntelliJ 就能够对可能出现的 null 值进行警告. +* 对于那些没有添加注解的可变（not-final）字段，就无法确定字段值是否为 null。 + * 此时应该仔细的检查这些值在对象的整个生命周期中是否可以不为 null。 -`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`. -See also [usage of Java Optional](code-style-and-quality-java.md#java-optional). +_注意: 大部分情况下是不需要 `@Nonnull` 注解的，但有些时候可以用来覆盖之前的注解，或者在不可以为 null 的上下文（Context）中，还想要得到 null 值。_ +对于不确定是否有结果返回的方法，`Optional` 作为方法的返回类型是个很好的解决方案，可以用 `Optional` 来代替所有可以为 null 的返回类型。 +参考 [Java Optional 的用法](code-style-and-quality-java.zh.md#java-optional). -### Avoid Code Duplication -1. Whenever you are about to copy/paste some code, or reproduce a similar type of functionality in a different place, think about the ways how to refactor/reuse/abstract the changes to avoid the duplication. -2. Common behavior between different specializations should be shared in a common component (or a shared superclass). -3. Always use “private static final” constants instead of duplicating strings or other special values at different locations. Constants should be declared in the top member area of a class. +### 避免重复的代码 +1. 当你准备复制/粘贴一些代码，或者在不同的地方实现类似的功能时，就要考虑怎么去重构、复用、抽象来避免重复的代码。 +2. 不同模块之间的相同特性应该抽象到公共组件（或父类）中。 +3. 常量应该声明在类顶部的成员区域中，并且是使用“private static final”修饰，而不是在不同的地方复制。 Review comment: ```suggestion 3. 常量应该声明在类顶部的成员区域中，并且是使用 “private static final” 修饰，而不是在不同的地方复制。 ``` ########## File path: contributing/code-style-and-quality-common.zh.md ########## @@ -30,95 +32,101 @@ Each file must include the Apache license information as a header. */ ``` -## 2. Tools +<a name="tools"></a> + +<a name="tools"></a> -We recommend to follow the [IDE Setup Guide](https://ci.apache.org/projects/flink/flink-docs-master/flinkDev/ide_setup.html#checkstyle-for-java) to get IDE tooling configured. +## 2. 工具 + +我们建议你按照 [IDE 设置指南](https://ci.apache.org/projects/flink/flink-docs-master/flinkDev/ide_setup.html#checkstyle-for-java) 配置 IDE 工具。 <!--- -### Use inspections in IntelliJ +### 在 IntelliJ 中使用检查 -* Import the inspections settings into the IDE (see IDE setup guide) - * TODO: Need to agree on a profile and export it (like checkstyle) -* Write the code such that inspection warnings are addressed - * There are few exceptions where an inspection warning is not meaningful. In that case, suppress the inspection warning. +* 将检查设置导入到 IDE (参阅 IDE 设置指南) + * TODO: 需要同意导出配置文件 (如 checkstyle) +* 编码解决检查警告 + * 当出现没有意义的检查警告时，应该禁止该警告，虽然这种情况很少。 --> -### Warnings +### 警告 + +* 我们争取实现零警告 +* 尽管现有的代码中存在许多警告，但新的修改不应该有任何编译器警告 +* 如果不能用合理的方式处理警告（某些情况下使用泛型时）也应该添加注释以压制警告 +* 弃用方法时，检查是否会引入其他的警告 -* We strive for zero warnings -* Even though there are many warnings in existing code, new changes should not add any additional compiler warnings -* If it is not possible to address the warning in a sane way (in some cases when working with generics) add an annotation to suppress the warning -* When deprecating methods, check that this does not introduce additional warnings +<a name="comments-and-code-readability"></a> -## 3. Comments And Code Readability +## 3. 注释和代码可读性 -### Comments +### 注释 -**Golden rule: Comment as much as necessary to support code understanding, but don’t add redundant information.** +**黄金法则: 尽可能多的注释以支持代码的理解，但不要添加多余的信息。** -Think about +思考 -* <span style="text-decoration:underline;">What</span> is the code doing? -* <span style="text-decoration:underline;">How</span> does the code do this? -* <span style="text-decoration:underline;">Why</span> is the code like that? +* <span style="text-decoration:underline;">What</span> 代码在做什么？ +* <span style="text-decoration:underline;">How</span> 代码怎么做到的？ +* <span style="text-decoration:underline;">Why</span> 代码为什么是这样的？ -The code alone should explain as much as possible the “<span style="text-decoration:underline;">what</span>” and the “<span style="text-decoration:underline;">how</span>” +代码本身应该尽可能的解释 “<span style="text-decoration:underline;">what</span>” 和 “<span style="text-decoration:underline;">how</span>” -* Use JavaDocs to describe the roles of classes and the contracts of methods, in cases where the contract is not obvious or intuitive from the method name (the “what”). -* The flow of the code should give a good description of the “how”. -Think of variable and method names as part of the code documenting itself. -* It often makes reading the code easier if larger blocks that form a unit are moved into a private method with a descriptive name of what that block is doing +* 使用 JavaDocs 来描述类的作用和方法的协议，以防止不能从方法名看出协议（“what”）。 +* 代码流程应该能够很好的描述 “how”。 +将变量和方法名看作是代码文档的一部分。 +* 如果将组成单元较大块的代码移动到 private 方法中，并且该方法具有描述性的名称，那么代码的可读性就会更强。 -In-code comments help explain the <span style="text-decoration:underline;">“why”</span> +代码内部的注释有助于解释 <span style="text-decoration:underline;">“why”</span> -* For example `// this specific code layout helps the JIT to better do this or that` -* Or `// nulling out this field here means future write attempts are fail-fast` -* Or `// for arguments with which this method is actually called, this seemingly naive approach works actually better than any optimized/smart version` +* 例如 `// 这种特定的代码布局可以让 JIT 更好的进行工作` +* 或 `// 此字段为空将会导致写入尝试 fail-fast` +* 或 `// 用于实际调用该方法的参数，这种看似简单的方式实际上比任何优化/智能版本更好` -In-code comments should not state redundant information about the “what” and “how” that is already obvious in the code itself. +在代码注释中，不应该有关于 “what” 和 “how” 这么明显的冗余信息。 -JavaDocs should not state meaningless information (just to satisfy the Checkstyle checker). +JavaDocs 不应该说明无意义的信息 （这么做只是为了满足 Checkstyle 的检查）。 -__Don’t:__ +__反例：__ ``` /** - * The symbol expression. + * 符号表达式。 */ public class CommonSymbolExpression {} ``` -__Do:__ +__正例：__ ``` /** - * An expression that wraps a single specific symbol. - * A symbol could be a unit, an alias, a variable, etc. + * 包含单个特定符号的表达式。 + * 符号可以是 Unit、Alias、Variable 等等。 */ public class CommonSymbolExpression {} ``` -### Branches and Nesting +### 分支和嵌套 -Avoid deep nesting of scopes, by flipping the if condition and exiting early. +通过对 if 条件取反并提前退出，避免超出嵌套深度的范围。 -__Don’t:__ +__反例：__ ``` if (a) { - if (b) { + if (b) { Review comment: 这个修改不需要，改回去吧 ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: us...@infra.apache.org
