ClownfishYang commented on a change in pull request #394: URL: https://github.com/apache/flink-web/pull/394#discussion_r531823381
########## File path: contributing/code-style-and-quality-common.zh.md ########## @@ -30,83 +32,88 @@ Each file must include the Apache license information as a header. */ ``` -## 2. Tools +<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: ```suggestion * 代码流程应该能够很好的描述 “how”，能够将变量和方法名看作是代码文档的一部分。 ``` ---------------------------------------------------------------- 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]
