1. 2006-03-22 校对记要

校对文件: roman.xml

章节第14章

已确定,所有的test case都翻译成“测试用例”


Test-First Programming 标题的翻译

{i} 这个来源于极限编程,强调先写测试,就是test-driven development,所以是不是该译成 “以测试优先为原则的编程”“以测试第一为原则的编程”。本想这样译:“测试第一的编程”,但感觉好像有歧义,待讨论。

JasonXie 有同感,译作 测试导向编程 如何?


1.1. 第14章第1节 roman.py, 第 1 阶段

http://www.woodpecker.org.cn/obp/diveintopython-zh-5.4/zh-cn/dist/htmlflat/diveintopython.html#roman.stage1

第一段

  • Now that the unit tests are complete, it's time to start writing the code that the test cases are attempting to test. You're going to do this in stages, so you can see all the unit tests fail, then watch them pass one by one as you fill in the gaps in roman.py.
  • 到目前为止,单元测试已经完成, <!> 到了 是时候 开始编写被单元测试测试的代码 的时候 了。你将 <!> 一步步 分阶段地 完成这个工作, <!> 你将看到所有的单元测试都是失败的,然后一个个攻破也同时填充了 roman.py 因此开始时所有的单元测试都是失败的,但在逐步完成roman.py的同时你会看到它们一个个地通过(测试)

JasonXie 同意修改


说明例子代码的句子

  • This file is available in py/roman/stage1/ in the examples directory.
  • <!> 这个程序可以 在例子目录下的py/roman/stage1/ 的 examples 目录中获得 找到

  • {i} 我下载了源码包,py/roman/stage1/是其中的一个目录。

JasonXie 同意,翻译仓促,我的疏忽


程序注解第1点的第2句

  • Exceptions are classes, and you create your own by subclassing existing exceptions.
  • <!> 你可以通过建立已有异常的子类来构建。 异常也是类,通过继承已有的异常,你可以创建自定义的异常。

  • {i} 这里,Exception似乎不翻译过来更好。

JasonXie 同意,译作Exception(异常)如何?


程序注解第1点的第3句

  • It is strongly recommended (but not required) that you subclass Exception, which is the base class that all built-in exceptions inherit from.
  • 强烈建议(但不是必须)你 <!> 从建立 Exception 这个所有内建异常的父类的子类入手 继承Exception来定义自己的异常,因为它是所有内建异常的基类

JasonXie 同意,我原本的翻译没有突出Subclass的动词含义。修改后因为有些不通。可否改作Exception是所有内建异常的基类,强烈建议(但不是必须)你也从它继承来生成自己的异常


程序注解第1点的第5句

  • This is a matter of style
  • 这是 <!> 一个风格问题 个人习惯的问题

JasonXie 无伤大雅,osmond统稿时定夺


程序注解的最后一点

  • At this stage, you want to define the API of each of your functions, but you don't want to code them yet, so you stub them out using the Python reserved word pass.
  • 在这一步中你 <!> 需要 只是想定义每个函数的 API , <!> 但是你不需要立刻编写他们 而不想具体实现它们<!> 而是 因此你以 Python 关键字 pass 一笔带过。

JasonXie 改的好! 若把最后的一笔带过,改做姑且带过,还能突出以后替换pass的含义,是否更好?


第一个程序注解后面的第一段

  • Now for the big moment (drum roll please): you're finally going to run the unit test against this stubby little module. At this point, every test case should fail. In fact, if any test case passes in stage 1, you should go back to romantest.py and re-evaluate why you coded a test so useless that it passes with do-nothing functions.
  • 重要的时刻到了(请打起鼓来):你终于要对这个简陋的小模块开始运行单元测试了。 目前而言,每一个 <!> 独立测试 <!> 都应该失败。 事实上,任何 <!> 独立测试 <!> <!> 在第 1 步 在此时通过,你都 <!> 因该返回 应该回头看看 romantest.py 重新评价一下<!> 为什么你的 仔细想想为什么你写的 测试代码如此没用, <!> 以至于连什么都不作的函数都能通过测试。

  • {i} <!> 独立测试 (!) 测试用例 (!)

JasonXie 改的好


第2个程序注解中第1点的第2句

  • For each test case, it prints out the doc string of the method and whether that test passed or failed.
  • 对于每个 <!> 独立测试 <!> ,无论测试通过与否,都会输出 doc string 这个方法的doc字符串

  • {i} <!> 独立测试 <!> (!) 测试用例 (!)

  • {i} doc string 是Python特有的注释,这里作者想强调unittest会把unittest的方法的doc string打印出来,所以我把the method翻译出来。string倒是没必要翻译。

JasonXie 同意,不知道行内有没有把 doc string完全翻译出来(比如:文档字符串,或者注释文档字符串)的做法


第2个程序注解中第3点

  • After the detail, unittest displays a summary of how many tests were performed and how long it took.
  • 在这些细节后面, unittest 给出了一个关于测试运行的总结和运行耗时 被执行测试的个数和花费时间的总结

JasonXie 同意,当时没想出合适的说法,这样改就像IT书了。哈哈!


第2个程序注解中第1点的第4句

  • Overall, the unit test failed because at least one test case did not pass. When a test case doesn't pass, unittest distinguishes between failures and errors. A failure is a call to an assertXYZ method, like assertEqual or assertRaises, that fails because the asserted condition is not true or the expected exception was not raised. An error is any other sort of exception raised in the code you're testing or the unit test case itself. For instance, the testFromRomanCase method (“fromRoman should only accept uppercase input”) was an error, because the call to numeral.upper() raised an AttributeError exception, because toRoman was supposed to return a string but didn't. But testZero (“toRoman should fail with 0 input”) was a failure, because the call to fromRoman did not raise the InvalidRomanNumeral exception that assertRaises was looking for.

  • 总而言之,任何 由于至少 一个 <!> 独立测试 <!> 不能 没有 通过 都会导致单元测试失败 ,单元测试失败了 一个 <!> 独立测试 <!> 没能通过 没能通过时 , unittest 能在失败和错误间进行分辨 会区分是失败(failures)还是错误(errors)。 失败 是指 调用 assertXYZ 方法 , 比如: assertEqual 或者 assertRaises (比如assertEqual 或者 assertRaises)时证明这个失败可能是由于例外情况的产生或者预期异常没有引发而导致 断言的情况没有发生或预期的异常没有被引发一个 错误 不是任何类型的异常溢出或者单元测试本身的问题 是指你测试的代码或单元测试本身发生了某种异常。例如:testFromRomanCase 方法 (“fromRoman 只接受大写输入”)就是一个错误,因为调用 numeral.upper() 引发了一个 AttributeError 异常,因为没有返回 toRoman 支持的字符串类型的返回值 toRoman的返回值不是期望的字符串类型。 但是, testZero (“toRoman 应该在输入 0 时失败”)是一个失败,因为调用 fromRoman 没有引发一个 assertRaises 期待的异常: InvalidRomanNumeral

JasonXie 可以