Question

拜托那位英语高手帮我翻译下啊 ~急用 别用翻译软件啊！

3.5 How to Document Wisely
Life is too short to write crap nobody will read; if you write crap, nobody
will read it. Therefore a little good documentation is best. Managers often
don't understand this, because even bad documentation gives them a false sense
of security that they are not dependent on their programmers. If someone
absolutely insists that you write truly useless documentation, say \yes" and
quietly begin looking for a better job.
There's nothing quite as effective as putting an accurate estimate of the
amount of time it will take to produce good documentation into an estimate to
slacken the demand for documentation. The truth is cold and hard: documentation,
like testing, can take many times longer than developing code.
17
Writing good documentation is, _rst of all, good writing. I suggest you
_nd books on writing, study them, and practice. But even if you are a lousy
writer or have poor command of the language in which you must document,
the Golden Rule is all you really need: \Do unto others as you would have
them do unto you." Take time to really think about who will be reading your
documentation, what they need to get out of it, and how you can teach that to
them. If you do that, you will be an above average documentation writer, and
a good programmer.
When it comes to actually documenting code itself, as opposed to producing
documents that can actually be read by non-programmers, the best programmers
I've ever known hold a universal sentiment: write self-explanatory code
and only document code in the places that you cannot make it clear by writing
the code itself. There are two good reasons for this. First, anyone who needs
to see code-level documentation will in most cases be able to and prefer to read
the code anyway. Admittedly, this seems easier to the experienced programmer
than to the beginner. More importantly however, is that the code and the
documentation cannot be inconsistent if there is no documentation. The source
code can at worst be wrong and confusing. The documentation, if not written
perfectly, can lie, and that is a thousand times worse.
This does not make it easier on the responsible programmer. How does one
write self-explanatory code? What does that even mean? It means:
_ Writing code knowing that someone will have to read it;
_ Applying the golden rule;
_ Using whatever rules of good writing you may have learned;
_ Choosing a solution that is straightforward, even if you could get by with
another solution faster;
_ Sacri_cing small optimizations that obfuscate the code;
_ Thinking about the reader and spending some of your precious time to
make it easier on her; and
_ Not ever using a function name like \foo",\bar", or \doIt"!

Answer 1

怎样明智地写文件

生命短暂以至你写了些垃圾出来也没人会浪费时间去看的，如果你尽写了些没用的，没人会阅读它。所以写一点短小的文章是必要的。管理者常常不懂这个，因为不好的文件给了他们一个关于安全性的错误的概念：他们觉得他们不用依赖你这个程序策划员。如果有人非常非常坚持认为你写了些没用的文件的话，你就说“是的没错”，然后迅速寻找一个新的活儿吧。
没有什么东西真的一样的有效率……

而事实是冷酷和艰难的：文件，像考试一样，很多时候都是事业发展的密码，

写出好的文件就是，首先，良好的写作水平。我建议你阅读些写作的书籍，认真学习他们，然后实践。但如果你写作很差劲，或者对你必须要用来写作的语言很生疏的呼，务必要遵循一条黄金守则，那就是：不要删除掉你本来该保留的东西，多花些时间去考虑谁会认真读你的文章，阅读的人在文章之外所需要的是什么，以及你要用什么方式教他们。如果你这样做，你肯定会成为一个卓尔不群的写作者，并且是一位好的程序员。

抱歉楼主 我要累死了 明天继续翻。

又翻了点 下午继续

Answer 2

3.5如何文件明智
生命太短，写crap ，没有人会读;如果你写crap ，没有人
会阅读它。因此，有点好文件是最好的。管理者往往
不明白这一点，因为即使是坏的文件，让他们有一个虚假的安全感
安全，他们不依赖于他们的程序员。如果有人
绝对坚持认为你写真正无用的文件，说\是“和
悄悄地开始寻觅工作做得更好。
没有什么能比得上作为有效的把准确估计有关
大量的时间将会采取何种措施产生良好的文件成为一个估计
放松的需求文档。事实是，冷战和努力：文件，
想测试，可以采取许多倍的时间比发展中国家的代码。
17
良好的书面文件， _rst所有，良好的写作。我建议你
_nd书籍，写作，研究，和实践。不过，即使你是一个糟糕的
作家或有穷人的指挥语言，在其中你必须的文件，
金科玉律是所有你真的需要： \己所不欲，正如你将有
他们己所不欲，你“需要一段时间真的觉得谁在将读您的
文件，他们所需要的失控，以及您如何可以教导，以
他们。如果你这样做，你将是一个高于平均水平的文件作家，和
一个很好的程序员。
当谈到，其实记录代码本身，作为反对生产
文件指出，其实是可以阅读的非程序员，最好的程序员
我从未已知举行一个普遍的感受：写自我解释性代码
只有文件的代码的地方，你不能作出澄清，以书面
代码本身。有两个很好的理由。第一，谁需要
看到代码级别的文件将在大多数情况下，能够和喜欢阅读
代码无论如何。诚然，这似乎更容易向有经验的程序员
比对初学者。更重要的，但是该守则和
文件不能不一致的，如果没有文件。来源
代码可以在最坏的错误的和混乱。文件，如果不写
完美，可以说谎，这是一个几千倍更糟。
这并不使其更易于对负责的程序员。请问1
写自我解释性代码？这代表了什么，甚至什么意思？这意味着：
_写代码知道会有人要读它;
_应用的金科玉律;
_使用什么规则，良好的写作，你可能有教训;
_选择的解决办法很简单，即使您可以得到与
另一种解决办法更快;
_ sacri_cing小优化，模糊码;
_思考的读者和消费您的一些宝贵的时间
使其更易于对她的;
_不要使用函数名称一样， \富“ ， \网吧” ，或\经济部“ ！