You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@flink.apache.org by GitBox <gi...@apache.org> on 2020/05/06 02:47:32 UTC
[GitHub] [flink-web] klion26 commented on a change in pull request #267: [FLINK-13682][docs-zh] Translate "Code Style - Scala Guide" page into Chinese
klion26 commented on a change in pull request #267:
URL: https://github.com/apache/flink-web/pull/267#discussion_r420509939
##########
File path: contributing/code-style-and-quality-scala.zh.md
##########
@@ -8,68 +8,67 @@ title: "Apache Flink Code Style and Quality Guide — Scala"
-## Scala Language Features
+## Scala 语言特性
-### Where to use (and not use) Scala
+### 在哪儿使用（和不使用） Scala
-**We use Scala for Scala APIs or pure Scala Libraries.**
+**我们使用 Scala 的 API 或者纯 Scala 库。**
Review comment:
这句话应该是说“对于 Scala 的 API 或者纯 Scala 的 libraries，我们会使用 Scala” 当然需要再组织下语言，看怎么描述会更合适
##########
File path: contributing/code-style-and-quality-scala.zh.md
##########
@@ -8,68 +8,67 @@ title: "Apache Flink Code Style and Quality Guide — Scala"
-## Scala Language Features
+## Scala 语言特性
-### Where to use (and not use) Scala
+### 在哪儿使用（和不使用） Scala
-**We use Scala for Scala APIs or pure Scala Libraries.**
+**我们使用 Scala 的 API 或者纯 Scala 库。**
-**We do not use Scala in the core APIs and runtime components. We aim to remove existing Scala use (code and dependencies) from those components.**
+**在 core API 和 运行时的组件中，我们不使用 Scala。我们的目标是从这些组件中删除现有的 Scala 使用(代码和依赖项)。**
-⇒ This is not because we do not like Scala, it is a consequence of “the right tool for the right job” approach (see below).
+⇒ 这并不是因为我们不喜欢 Scala，而是考虑到“用正确的工具做正确的事”的结果（见下文）。
-For APIs, we develop the foundation in Java, and layer Scala on top.
+对于 API，我们使用 Java 开发基础内容，并在上层使用 Scala。
-* This has traditionally given the best interoperability for both Java and Scala
-* It does mean dedicated effort to keep the Scala API up to date
+* 这在传统上为 Java 和 Scala 提供了最佳的互通性
+* 这意味着要致力于保持 Scala API 的更新
-Why don’t we use Scala in the core APIs and runtime?
+为什么我们不在 core API 和运行时中使用 Scala ？
-* The past has shown that Scala evolves too quickly with tricky changes in functionality. Each Scala version upgrade was a rather big effort process for the Flink community.
-* Scala does not always interact nicely with Java classes, e.g. Scala’s visibility scopes work differently and often expose more to Java consumers than desired
-* Scala adds an additional layer of complexity to artifact/dependency management.
- * We may want to keep Scala dependent libraries like Akka in the runtime, but abstract them via an interface and load them in a separate classloader, to keep them shielded and avoid version conflicts.
-* Scala makes it very easy for knowledgeable Scala programmers to write code that is very hard to understand for programmers that are less knowledgeable in Scala. That is especially tricky for an open source project with a broad community of diverse experience levels. Working around this means restricting the Scala feature set by a lot, which defeats a good amount of the purpose of using Scala in the first place.
+* 过去的经验显示， Scala 在功能上的变化太快了。对于 Flink 社区来说，每次 Scala 版本升级都是一个需要付出相当大努力的过程。
+* Scala 并不总能很好地与 Java 的类交互，例如 Scala 的可见性范围的工作方式不同，而且常常向 Java 消费者公开的内容比预期的要多。
+* Scala artifact/dependency 的管理增加了一层额外的复杂性。
+ * 我们可能希望在运行时保留像 Akka 这样依赖 Scala 的库，但是要通过接口抽象它们，并在单独的类加载器中加载它们，以保护它们并避免版本冲突。
+* Scala 让懂 Scala 的程序员很容易编写代码，而对于不太懂 Scala 的程序员来说，这些代码很难理解。对于一个拥有不同经验水平的广大社区的开源项目来说，这尤其棘手。解决这个问题意味着大量限制 Scala 特性集，这首先就违背了使用 Scala 的很多目的。
-### API Parity
+### API 同等
-Keep Java API and Scala API in sync in terms of functionality and code quality.
+保持 Java API 和 Scala API 在功能和代码质量方面的同步。
-The Scala API should cover all the features of the Java APIs as well.
+Scala API 也应该涵盖 Java API 的所有特性。
-Scala APIs should have a “completeness test”, like the following example from the DataStream API: [https://github.com/apache/flink/blob/master/flink-streaming-scala/src/test/scala/org/apache/flink/streaming/api/scala/StreamingScalaAPICompletenessTest.scala](https://github.com/apache/flink/blob/master/flink-streaming-scala/src/test/scala/org/apache/flink/streaming/api/scala/StreamingScalaAPICompletenessTest.scala)
+Scala API 应该有一个“完整性测试”，就如下面 DataStream API 的示例中的一样： [https://github.com/apache/flink/blob/master/flink-streaming-scala/src/test/scala/org/apache/flink/streaming/api/scala/StreamingScalaAPICompletenessTest.scala](https://github.com/apache/flink/blob/master/flink-streaming-scala/src/test/scala/org/apache/flink/streaming/api/scala/StreamingScalaAPICompletenessTest.scala)
-### Language Features
+### 语言特性
-* **Avoid Scala implicits.**
- * Scala’s implicits should only be used for user-facing API improvements such as the Table API expressions or type information extraction.
- * Don’t use them for internal “magic”.
-* **Add explicit types for class members.**
- * Don’t rely on implicit type inference for class fields and methods return types:
+* **避免 Scala 隐式转换。**
+ * Scala 的隐式转换应该只用于面向用户的 API 改进，例如 Table API 表达式或类型信息提取。
+ * 不要把它们用于内部 “magic”。
+* **为类成员添加显式类型。**
+ * 对于类字段和方法返回类型，不要依赖隐式类型推断:
- **Don’t:**
+ **不要这样：**
```
var expressions = new java.util.ArrayList[String]()
```
- **Do:**
+ **要这样：**
```
var expressions: java.util.List[String] = new java.util.ArrayList[]()
```
- * Type inference for local variables on the stack is fine.
-* **Use strict visibility.**
- * Avoid Scala’s package private features (such as private[flink]) and use regular private/protected instead.
- * Keep in mind that `private[flink]` and `protected` members are public in Java.
- * Keep in mind that `private[flink]` still exposes all members in Flink provided examples.
+ * 堆栈上局部变量的类型推断是可以的。
+* **用严格的可见性。**
+ * 避免使用 Scala 的包私有特性(如 private[flink])，而是使用常规 private/protected 替代。
+ * 请注意：在 Java 中，`private[flink]` 和 `protected` 的成员是公开的。
+ * 请注意：在 Flink 提供的示例中， `private[flink]` 仍然会暴露所有成员。
+### 编码格式
-### Coding Formatting
+**使用换行来构造你的代码。**
-**Use line wrapping to structure your code.**
-
-* Scala’s functional nature allows for long transformation chains (`x.map().map().foreach()`).
-* In order to force implementers to structure their code, the line length is therefore limited to 100 characters.
-* Use one line per transformation for better maintainability.
+* Scala 的函数性质允许长的转换链（ `x.map().map().foreach()` ）。
+* 为了强制让实现者构造其代码，行长度因此被限制为 100 个字符。
Review comment:
"行长度因此被限制" 改为 “因此行长度被限制” 是不是更好？
##########
File path: contributing/code-style-and-quality-scala.zh.md
##########
@@ -8,68 +8,67 @@ title: "Apache Flink Code Style and Quality Guide — Scala"
-## Scala Language Features
+## Scala 语言特性
-### Where to use (and not use) Scala
+### 在哪儿使用（和不使用） Scala
-**We use Scala for Scala APIs or pure Scala Libraries.**
+**我们使用 Scala 的 API 或者纯 Scala 库。**
-**We do not use Scala in the core APIs and runtime components. We aim to remove existing Scala use (code and dependencies) from those components.**
+**在 core API 和 运行时的组件中，我们不使用 Scala。我们的目标是从这些组件中删除现有的 Scala 使用(代码和依赖项)。**
-⇒ This is not because we do not like Scala, it is a consequence of “the right tool for the right job” approach (see below).
+⇒ 这并不是因为我们不喜欢 Scala，而是考虑到“用正确的工具做正确的事”的结果（见下文）。
-For APIs, we develop the foundation in Java, and layer Scala on top.
+对于 API，我们使用 Java 开发基础内容，并在上层使用 Scala。
-* This has traditionally given the best interoperability for both Java and Scala
-* It does mean dedicated effort to keep the Scala API up to date
+* 这在传统上为 Java 和 Scala 提供了最佳的互通性
+* 这意味着要致力于保持 Scala API 的更新
-Why don’t we use Scala in the core APIs and runtime?
+为什么我们不在 core API 和运行时中使用 Scala ？
-* The past has shown that Scala evolves too quickly with tricky changes in functionality. Each Scala version upgrade was a rather big effort process for the Flink community.
-* Scala does not always interact nicely with Java classes, e.g. Scala’s visibility scopes work differently and often expose more to Java consumers than desired
-* Scala adds an additional layer of complexity to artifact/dependency management.
- * We may want to keep Scala dependent libraries like Akka in the runtime, but abstract them via an interface and load them in a separate classloader, to keep them shielded and avoid version conflicts.
-* Scala makes it very easy for knowledgeable Scala programmers to write code that is very hard to understand for programmers that are less knowledgeable in Scala. That is especially tricky for an open source project with a broad community of diverse experience levels. Working around this means restricting the Scala feature set by a lot, which defeats a good amount of the purpose of using Scala in the first place.
+* 过去的经验显示， Scala 在功能上的变化太快了。对于 Flink 社区来说，每次 Scala 版本升级都是一个需要付出相当大努力的过程。
Review comment:
这里是不是应该把 “tricky change”也描述出来更好。
##########
File path: contributing/code-style-and-quality-scala.zh.md
##########
@@ -8,68 +8,67 @@ title: "Apache Flink Code Style and Quality Guide — Scala"
-## Scala Language Features
+## Scala 语言特性
-### Where to use (and not use) Scala
+### 在哪儿使用（和不使用） Scala
-**We use Scala for Scala APIs or pure Scala Libraries.**
+**我们使用 Scala 的 API 或者纯 Scala 库。**
-**We do not use Scala in the core APIs and runtime components. We aim to remove existing Scala use (code and dependencies) from those components.**
+**在 core API 和 运行时的组件中，我们不使用 Scala。我们的目标是从这些组件中删除现有的 Scala 使用(代码和依赖项)。**
-⇒ This is not because we do not like Scala, it is a consequence of “the right tool for the right job” approach (see below).
+⇒ 这并不是因为我们不喜欢 Scala，而是考虑到“用正确的工具做正确的事”的结果（见下文）。
-For APIs, we develop the foundation in Java, and layer Scala on top.
+对于 API，我们使用 Java 开发基础内容，并在上层使用 Scala。
-* This has traditionally given the best interoperability for both Java and Scala
-* It does mean dedicated effort to keep the Scala API up to date
+* 这在传统上为 Java 和 Scala 提供了最佳的互通性
+* 这意味着要致力于保持 Scala API 的更新
-Why don’t we use Scala in the core APIs and runtime?
+为什么我们不在 core API 和运行时中使用 Scala ？
-* The past has shown that Scala evolves too quickly with tricky changes in functionality. Each Scala version upgrade was a rather big effort process for the Flink community.
-* Scala does not always interact nicely with Java classes, e.g. Scala’s visibility scopes work differently and often expose more to Java consumers than desired
-* Scala adds an additional layer of complexity to artifact/dependency management.
- * We may want to keep Scala dependent libraries like Akka in the runtime, but abstract them via an interface and load them in a separate classloader, to keep them shielded and avoid version conflicts.
-* Scala makes it very easy for knowledgeable Scala programmers to write code that is very hard to understand for programmers that are less knowledgeable in Scala. That is especially tricky for an open source project with a broad community of diverse experience levels. Working around this means restricting the Scala feature set by a lot, which defeats a good amount of the purpose of using Scala in the first place.
+* 过去的经验显示， Scala 在功能上的变化太快了。对于 Flink 社区来说，每次 Scala 版本升级都是一个需要付出相当大努力的过程。
+* Scala 并不总能很好地与 Java 的类交互，例如 Scala 的可见性范围的工作方式不同，而且常常向 Java 消费者公开的内容比预期的要多。
+* Scala artifact/dependency 的管理增加了一层额外的复杂性。
Review comment:
这个地方应该是说，“因为使用 Scala 所以 Flink 的 artifact/dependency 管理增加了一层额外的复杂性”？
##########
File path: contributing/code-style-and-quality-scala.zh.md
##########
@@ -8,68 +8,67 @@ title: "Apache Flink Code Style and Quality Guide — Scala"
-## Scala Language Features
+## Scala 语言特性
-### Where to use (and not use) Scala
+### 在哪儿使用（和不使用） Scala
-**We use Scala for Scala APIs or pure Scala Libraries.**
+**我们使用 Scala 的 API 或者纯 Scala 库。**
-**We do not use Scala in the core APIs and runtime components. We aim to remove existing Scala use (code and dependencies) from those components.**
+**在 core API 和 运行时的组件中，我们不使用 Scala。我们的目标是从这些组件中删除现有的 Scala 使用(代码和依赖项)。**
-⇒ This is not because we do not like Scala, it is a consequence of “the right tool for the right job” approach (see below).
+⇒ 这并不是因为我们不喜欢 Scala，而是考虑到“用正确的工具做正确的事”的结果（见下文）。
-For APIs, we develop the foundation in Java, and layer Scala on top.
+对于 API，我们使用 Java 开发基础内容，并在上层使用 Scala。
-* This has traditionally given the best interoperability for both Java and Scala
-* It does mean dedicated effort to keep the Scala API up to date
+* 这在传统上为 Java 和 Scala 提供了最佳的互通性
+* 这意味着要致力于保持 Scala API 的更新
-Why don’t we use Scala in the core APIs and runtime?
+为什么我们不在 core API 和运行时中使用 Scala ？
-* The past has shown that Scala evolves too quickly with tricky changes in functionality. Each Scala version upgrade was a rather big effort process for the Flink community.
-* Scala does not always interact nicely with Java classes, e.g. Scala’s visibility scopes work differently and often expose more to Java consumers than desired
-* Scala adds an additional layer of complexity to artifact/dependency management.
- * We may want to keep Scala dependent libraries like Akka in the runtime, but abstract them via an interface and load them in a separate classloader, to keep them shielded and avoid version conflicts.
-* Scala makes it very easy for knowledgeable Scala programmers to write code that is very hard to understand for programmers that are less knowledgeable in Scala. That is especially tricky for an open source project with a broad community of diverse experience levels. Working around this means restricting the Scala feature set by a lot, which defeats a good amount of the purpose of using Scala in the first place.
+* 过去的经验显示， Scala 在功能上的变化太快了。对于 Flink 社区来说，每次 Scala 版本升级都是一个需要付出相当大努力的过程。
+* Scala 并不总能很好地与 Java 的类交互，例如 Scala 的可见性范围的工作方式不同，而且常常向 Java 消费者公开的内容比预期的要多。
+* Scala artifact/dependency 的管理增加了一层额外的复杂性。
+ * 我们可能希望在运行时保留像 Akka 这样依赖 Scala 的库，但是要通过接口抽象它们，并在单独的类加载器中加载它们，以保护它们并避免版本冲突。
+* Scala 让懂 Scala 的程序员很容易编写代码，而对于不太懂 Scala 的程序员来说，这些代码很难理解。对于一个拥有不同经验水平的广大社区的开源项目来说，这尤其棘手。解决这个问题意味着大量限制 Scala 特性集，这首先就违背了使用 Scala 的很多目的。
-### API Parity
+### API 同等
Review comment:
这应该是说对于 API 来说是否使用 Scala 吧，上面说了两种情况下会使用 Scala（API 和 library）
##########
File path: contributing/code-style-and-quality-scala.zh.md
##########
@@ -8,68 +8,67 @@ title: "Apache Flink Code Style and Quality Guide — Scala"
-## Scala Language Features
+## Scala 语言特性
-### Where to use (and not use) Scala
+### 在哪儿使用（和不使用） Scala
-**We use Scala for Scala APIs or pure Scala Libraries.**
+**我们使用 Scala 的 API 或者纯 Scala 库。**
-**We do not use Scala in the core APIs and runtime components. We aim to remove existing Scala use (code and dependencies) from those components.**
+**在 core API 和 运行时的组件中，我们不使用 Scala。我们的目标是从这些组件中删除现有的 Scala 使用(代码和依赖项)。**
-⇒ This is not because we do not like Scala, it is a consequence of “the right tool for the right job” approach (see below).
+⇒ 这并不是因为我们不喜欢 Scala，而是考虑到“用正确的工具做正确的事”的结果（见下文）。
-For APIs, we develop the foundation in Java, and layer Scala on top.
+对于 API，我们使用 Java 开发基础内容，并在上层使用 Scala。
-* This has traditionally given the best interoperability for both Java and Scala
-* It does mean dedicated effort to keep the Scala API up to date
+* 这在传统上为 Java 和 Scala 提供了最佳的互通性
+* 这意味着要致力于保持 Scala API 的更新
-Why don’t we use Scala in the core APIs and runtime?
+为什么我们不在 core API 和运行时中使用 Scala ？
-* The past has shown that Scala evolves too quickly with tricky changes in functionality. Each Scala version upgrade was a rather big effort process for the Flink community.
-* Scala does not always interact nicely with Java classes, e.g. Scala’s visibility scopes work differently and often expose more to Java consumers than desired
-* Scala adds an additional layer of complexity to artifact/dependency management.
- * We may want to keep Scala dependent libraries like Akka in the runtime, but abstract them via an interface and load them in a separate classloader, to keep them shielded and avoid version conflicts.
-* Scala makes it very easy for knowledgeable Scala programmers to write code that is very hard to understand for programmers that are less knowledgeable in Scala. That is especially tricky for an open source project with a broad community of diverse experience levels. Working around this means restricting the Scala feature set by a lot, which defeats a good amount of the purpose of using Scala in the first place.
+* 过去的经验显示， Scala 在功能上的变化太快了。对于 Flink 社区来说，每次 Scala 版本升级都是一个需要付出相当大努力的过程。
+* Scala 并不总能很好地与 Java 的类交互，例如 Scala 的可见性范围的工作方式不同，而且常常向 Java 消费者公开的内容比预期的要多。
+* Scala artifact/dependency 的管理增加了一层额外的复杂性。
+ * 我们可能希望在运行时保留像 Akka 这样依赖 Scala 的库，但是要通过接口抽象它们，并在单独的类加载器中加载它们，以保护它们并避免版本冲突。
Review comment:
这句话能够有更好的翻译吗？这个翻译读起来怪怪的，现在的翻译读起来更像英文顺序。
能否改成更像中文的翻译呢？比如“我们希望通过接口抽象，同时也在运行时保留像 Akka 这样依赖 Scala 的库，XXX”
----------------------------------------------------------------
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:
users@infra.apache.org