ClownfishYang commented on a change in pull request #394: URL: https://github.com/apache/flink-web/pull/394#discussion_r531822683
########## 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: ```suggestion if (b) { ``` ---------------------------------------------------------------- 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: [email protected]
