真相在代码中 #1617

loveky · 2017-05-03T12:01:59Z

原文地址：The truth is in the code

原文作者：Bertil Muth

译文出自：掘金翻译计划

译者：loveky

校对者：

掘金链接：真相在代码中 #1595

PR地址：真相在代码中 #1617

loveky · 2017-05-03T12:02:36Z

@sqrthree 翻译完成，请求校对

sunui · 2017-05-04T10:53:48Z

@sqrthree 校对认领

linhe0x0 · 2017-05-04T13:53:24Z

@sunui 好的

aladdin-add · 2017-05-04T15:27:38Z

建议：标题可否改成：源码面前，了无秘密。(from 侯捷)

sunui

简洁明快翻译的很好。标题建议：真相就在代码指之中

sunui · 2017-05-04T14:23:50Z

TODO/the-truth-is-in-the-code.md


 ![](https://cdn-images-1.medium.com/max/800/1*Fw8F2fRNVfkcE-0VGyDZhQ.png)

-[shoppingapp](https://github.com/bertilmuth/requirementsascode/tree/master/requirementsascodeexamples/shoppingappjavafx) model, example of [requirementsascode](https://github.com/bertilmuth/requirementsascode)
+[shoppingapp](https://github.com/bertilmuth/requirementsascode/tree/master/requirementsascodeexamples/shoppingappjavafx) 模型, [requirementsascode](https://github.com/bertilmuth/requirementsascode) 的示例代码


中文逗号

sunui · 2017-05-04T14:28:48Z

TODO/the-truth-is-in-the-code.md


-> – Robert C. Martin, [Clean Code](https://www.amazon.de/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882)
+> – Robert C. Martin, [代码整洁之道](https://www.amazon.de/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882)


中文逗号和破折号书名号是不是也要加上

sunui · 2017-05-04T14:40:24Z

TODO/the-truth-is-in-the-code.md


-*X*: We can’t go on with feature *foo*.
+**X**: 我们不能继续开发**foo**特性了。


中英文之间空格

sunui · 2017-05-04T14:42:43Z

TODO/the-truth-is-in-the-code.md


-There are techniques for that. [Pair programming](https://en.m.wikipedia.org/wiki/Pair_programming) is a good one. Or you sit down with other developers. You walk them through the code you have written.
+有这方面的技术。[结对编程](https://en.m.wikipedia.org/wiki/Pair_programming)就是一个不错的选择。或者是和其他开发人员坐下来，一起过一遍你写的代码。


技术 => 技巧

sunui · 2017-05-04T14:56:13Z

TODO/the-truth-is-in-the-code.md


-Clean code gives you the right *words*.
+整洁代码带给你正确的**单词**。


单词 => 言辞

想了想，"用词"是不是更合适？言辞有点太正式了？

sunui · 2017-05-04T15:21:25Z

TODO/the-truth-is-in-the-code.md


-So if several developers use Rails, they know which part of the code to look at for certain parts of their story.
+因此，如果多个开发人员使用Rails，他们就知道在哪里能找到和故事中特定部分相关的代码。


中英文之间空格

sunui · 2017-05-04T15:22:14Z

TODO/the-truth-is-in-the-code.md


-They could find out what is missing when sharing their understanding. Then, they could agree on further conventions on where to put which part of their story.
+他们可以在分享他们的理解时找出缺失的东西。然后，他们就可以进一步的就约定在哪里放置故事的模块达成一致。


分享他们的理解 => 分享他们的见解

sunui · 2017-05-04T15:25:18Z

TODO/the-truth-is-in-the-code.md

- But the runner only reacts if the user is at the right position of the *flow* and the step’s *condition* is fulfilled. For example, the runner only reacts to the “EnterPaymentDetails“ event if the user has entered the shipping information right before.
- The *systemreaction* is a single method. The method’s body is responsible for coordinating the components to realize the step, as described in chapter 2.
- Chapter 3 is out of scope of requirementsascode. It is left up to the application. That makes requirementsascode compatible with arbitrary software designs.
+- UssCaseModel 实例用于定义**行为者**，**用例**，它们的**流程**以及**步骤**。它讲述故事的第一章。在本文的开头你能找到一个这种模型的例子。


UssCaseModel => UseCaseModel

sunui · 2017-05-04T15:26:16Z

TODO/the-truth-is-in-the-code.md

+- 用例模型配置 UseCaseModelRunner 实例。每个用户都有自己的运行程序，因为每个用户选择执行的用例路径可能不同。
+- 运行程序通过调用后端的**系统响应**来响应前端的**用户事件**。前端只能通过运行程序和后端通信。
+- 但是运行程序只有当用户在**流程**中的正确位置且满足步骤的**条件**时才会响应用户。例如：运行程序只有在用户已经输入了配送信息之后才会响应“进入支付详情页”事件。
+- **system reaction**是一个单例方法。方法内部负责协调不同组件以实现该步骤，就像在第二章中描述的那样。


中英文空格

sunui · 2017-05-04T15:28:46Z

TODO/the-truth-is-in-the-code.md


-You can [clone](https://github.com/bertilmuth/requirementsascode) the project and try it out yourself.
+你可以[克隆](https://github.com/bertilmuth/requirementsascode)这个项目并亲自尝试一下。


clone 和下文的 contribute 建议不翻译

contribute 不翻译是不是读起来就不通顺了。

也可以contribute在代码中记录真相？

sunui · 2017-05-04T15:32:04Z

@sqrthree @loveky 校对完成

yzgyyang · 2017-05-07T16:37:48Z

@sqrthree 认领

linhe0x0 · 2017-05-08T01:34:14Z

@yzgyyang 好哒

linhe0x0 · 2017-05-10T03:14:43Z

@yzgyyang 别忘了来校对啊

yzgyyang

@loveky @sqrthree 校对完成。翻译很棒！有一个总体的建议不知道对不对：原文里大量用短句，翻译过来句号特别多，有很多地方不必断句。建议改为逗号。

yzgyyang · 2017-05-11T04:36:56Z

TODO/the-truth-is-in-the-code.md


 ![](https://cdn-images-1.medium.com/max/800/1*Fw8F2fRNVfkcE-0VGyDZhQ.png)

-[shoppingapp](https://github.com/bertilmuth/requirementsascode/tree/master/requirementsascodeexamples/shoppingappjavafx) model, example of [requirementsascode](https://github.com/bertilmuth/requirementsascode)
+[shoppingapp](https://github.com/bertilmuth/requirementsascode/tree/master/requirementsascodeexamples/shoppingappjavafx) 模型，[requirementsascode](https://github.com/bertilmuth/requirementsascode) 的示例代码


建议翻译一下'shopping app'？个人观点。

yzgyyang · 2017-05-11T04:38:41Z

TODO/the-truth-is-in-the-code.md


-The [Agile Manifesto](http://agilemanifesto.org/) values “working software over comprehensive documentation.”
+[敏捷宣言](http://agilemanifesto.org/)中指出“可工作的软件胜过繁琐的文档。”


。” => ”。

yzgyyang · 2017-05-11T04:39:24Z

TODO/the-truth-is-in-the-code.md


-In contrast, code *always* reflects the software’s behavior. It defines it.
+另一方面，代码**始终**都能表达软件的行为。因为正是它定义了这些行为。


"另一方面" => "相反"

yzgyyang · 2017-05-11T04:40:03Z

TODO/the-truth-is-in-the-code.md


-Code comments, and external specifications, document the software’s behavior as well. But they may not get updated when the code changes. Then they stop reflecting the software’s behavior soon.
+代码注释，外部规范也在记录软件的行为。但是当代码被修改时它们可能不会被同步更新。然后它们很快就不再能表达代码的行为了。


"行为。但是" 这里的句号也许可以改为逗号？

yzgyyang · 2017-05-11T04:43:40Z

TODO/the-truth-is-in-the-code.md


-As a user of software, I want to [reach a desired outcome](https://medium.freecodecamp.com/nobody-wants-to-use-software-a75643bee654?source=linkShare-a74297325869-1489339708). For example, I want to own a new pair of gloves to keep my fingers warm in winter.
+作为一个软件的用户，我想要[达到期望的目的](https://medium.freecodecamp.com/nobody-wants-to-use-software-a75643bee654?source=linkShare-a74297325869-1489339708)。比如，我想拥有一双新手套以便我的手指在冬天可以保持温暖。


“以便我的手指在冬天可以保持温暖” =>“在冬天可以给我的手保暖”

yzgyyang · 2017-05-11T04:45:17Z

TODO/the-truth-is-in-the-code.md


-So I go online and see there is a new online shop specialized in gloves. The shop’s website lets me buy gloves. The “basic flow” (also called “happy day scenario”) of the use case could look like this one:
+因此我上网寻找并发现了一家新开的线上手套专卖店。该店铺的网站可以让我购买手套。“基本流程”（也被成为“正常用例”）大概是这样的：


“寻找并发现” => "找到"
“该店铺的网站可以让我购买手套” => "我可以在他们的网站上买手套"
"成为" => "称为"

yzgyyang · 2017-05-11T04:45:36Z

TODO/the-truth-is-in-the-code.md

+- 系统以一个空购物车开始。
+- 系统展示一个手套的列表。
+- 我添加喜欢的手套到购物车。系统将这些手套加入到我的订单中。
+- 我选择结账


标点符号

yzgyyang · 2017-05-11T04:48:17Z

TODO/the-truth-is-in-the-code.md


-It also bears the risk that developers tell too many different stories. Even for the same product. That makes it harder than necessary to understand code that somebody else has written.
+这也承担了由开发人员讲述太多不同故事（哪怕是针对同一个产品）带来的风险。使得理解其他人编写的代码变得更困难了。


可以改为逗号

yzgyyang · 2017-05-11T04:49:43Z

TODO/the-truth-is-in-the-code.md


-To learn whether the approach scales, I tried it on an application with several thousand lines of code. It worked. I tried it on smaller applications as well.
+为了了解这种方法是否具有可扩展性，我尝试在一个有数千行代码的项目中使用。被证明是有效的。我也在一些更加小型的应用中尝试过。


“被证明是有效的”前可以改为逗号

loveky · 2017-05-11T10:26:48Z

感谢 @yzgyyang 的校对。 @sqrthree 已经修改完毕。

linhe0x0

两个小问题辛苦改一下哈。

linhe0x0 · 2017-05-12T03:19:13Z

TODO/the-truth-is-in-the-code.md


-#### So what are the *parts* of a use case? ###
+#### 那么一个用例由哪些零件构成呢？####


linhe0x0 · 2017-05-12T03:19:30Z

TODO/the-truth-is-in-the-code.md


-#### To understand the code, you need an easy way to know several things. ###
+#### 要理解代码，你需要一个简单方法来了解几件事情。####


好尴尬，github不支持h4标签啊，这种一般要怎么处理呢

支持前后加 ### 号，但是要和内容之间保持一个空格。原句中的句号因为是全角符号，容易误解为已经存在空格了，实际是没有的。

loveky · 2017-05-12T03:31:20Z

@sqrthree 改好啦

linhe0x0 · 2017-05-12T03:32:19Z

@loveky 已经 merge 啦~ 快快麻溜发布到掘金专栏然后给我发下链接，方便及时添加积分哟。

loveky · 2017-05-12T03:43:57Z

已发布 https://juejin.im/post/59152d17da2f60005dd0ae77

感谢 @sunui @yzgyyang @sqrthree 各位的帮助

loveky added 3 commits May 3, 2017 14:37

save

ba71187

jiaoyan

0148db5

save

9071ad4

linhe0x0 self-requested a review May 4, 2017 02:10

linhe0x0 added the 校对认领 label May 4, 2017

linhe0x0 mentioned this pull request May 4, 2017

真相在代码中 #1595

Closed

linhe0x0 added the 正在校对 label May 4, 2017

sunui reviewed May 4, 2017

View reviewed changes

loveky added 2 commits May 5, 2017 08:06

update

ff6f064

save

ce4b84b

linhe0x0 removed the 校对认领 label May 8, 2017

yzgyyang reviewed May 11, 2017

View reviewed changes

loveky added 2 commits May 11, 2017 18:22

save

5d9b8b4

save

3b4c43e

增加校对者信息

3cf9d52

linhe0x0 approved these changes May 12, 2017

View reviewed changes

linhe0x0 requested changes May 12, 2017

View reviewed changes

Update the-truth-is-in-the-code.md

cd32cf6

linhe0x0 approved these changes May 12, 2017

View reviewed changes

linhe0x0 merged commit 1a8947e into xitu:master May 12, 2017

linhe0x0 added 翻译完成 and removed 正在校对 labels May 12, 2017


		> – Robert C. Martin, [Clean Code](https://www.amazon.de/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882)
		> – Robert C. Martin, [代码整洁之道](https://www.amazon.de/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882)


		X: We can’t go on with feature foo.
		X: 我们不能继续开发foo特性了。


		There are techniques for that. [Pair programming](https://en.m.wikipedia.org/wiki/Pair_programming) is a good one. Or you sit down with other developers. You walk them through the code you have written.
		有这方面的技术。[结对编程](https://en.m.wikipedia.org/wiki/Pair_programming)就是一个不错的选择。或者是和其他开发人员坐下来，一起过一遍你写的代码。


		Clean code gives you the right words.
		整洁代码带给你正确的单词。


		So if several developers use Rails, they know which part of the code to look at for certain parts of their story.
		因此，如果多个开发人员使用Rails，他们就知道在哪里能找到和故事中特定部分相关的代码。


		They could find out what is missing when sharing their understanding. Then, they could agree on further conventions on where to put which part of their story.
		他们可以在分享他们的理解时找出缺失的东西。然后，他们就可以进一步的就约定在哪里放置故事的模块达成一致。


		You can [clone](https://github.com/bertilmuth/requirementsascode) the project and try it out yourself.
		你可以[克隆](https://github.com/bertilmuth/requirementsascode)这个项目并亲自尝试一下。


		The [Agile Manifesto](http://agilemanifesto.org/) values “working software over comprehensive documentation.”
		[敏捷宣言](http://agilemanifesto.org/)中指出“可工作的软件胜过繁琐的文档。”


		In contrast, code always reflects the software’s behavior. It defines it.
		另一方面，代码始终都能表达软件的行为。因为正是它定义了这些行为。


		Code comments, and external specifications, document the software’s behavior as well. But they may not get updated when the code changes. Then they stop reflecting the software’s behavior soon.
		代码注释，外部规范也在记录软件的行为。但是当代码被修改时它们可能不会被同步更新。然后它们很快就不再能表达代码的行为了。


		As a user of software, I want to [reach a desired outcome](https://medium.freecodecamp.com/nobody-wants-to-use-software-a75643bee654?source=linkShare-a74297325869-1489339708). For example, I want to own a new pair of gloves to keep my fingers warm in winter.
		作为一个软件的用户，我想要[达到期望的目的](https://medium.freecodecamp.com/nobody-wants-to-use-software-a75643bee654?source=linkShare-a74297325869-1489339708)。比如，我想拥有一双新手套以便我的手指在冬天可以保持温暖。


		So I go online and see there is a new online shop specialized in gloves. The shop’s website lets me buy gloves. The “basic flow” (also called “happy day scenario”) of the use case could look like this one:
		因此我上网寻找并发现了一家新开的线上手套专卖店。该店铺的网站可以让我购买手套。“基本流程”（也被成为“正常用例”）大概是这样的：


		It also bears the risk that developers tell too many different stories. Even for the same product. That makes it harder than necessary to understand code that somebody else has written.
		这也承担了由开发人员讲述太多不同故事（哪怕是针对同一个产品）带来的风险。使得理解其他人编写的代码变得更困难了。


		To learn whether the approach scales, I tried it on an application with several thousand lines of code. It worked. I tried it on smaller applications as well.
		为了了解这种方法是否具有可扩展性，我尝试在一个有数千行代码的项目中使用。被证明是有效的。我也在一些更加小型的应用中尝试过。


		#### So what are the parts of a use case? ###
		#### 那么一个用例由哪些零件构成呢？####


		#### To understand the code, you need an easy way to know several things. ###
		#### 要理解代码，你需要一个简单方法来了解几件事情。####

真相在代码中 #1617

真相在代码中 #1617

Conversation

loveky commented May 3, 2017 • edited Loading

loveky commented May 3, 2017

sunui commented May 4, 2017

linhe0x0 commented May 4, 2017

aladdin-add commented May 4, 2017

sunui left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sunui commented May 4, 2017

yzgyyang commented May 7, 2017

linhe0x0 commented May 8, 2017

linhe0x0 commented May 10, 2017

yzgyyang left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

loveky commented May 11, 2017

linhe0x0 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

loveky commented May 12, 2017

linhe0x0 commented May 12, 2017

loveky commented May 12, 2017

loveky commented May 3, 2017 •

edited

Loading

sunui left a comment •

edited

Loading