春鱼2005-7-30

引言

作为开发人员，只要工作，就不可避免地要与文档打交道。我们恐怕都承认良好的文档书写能力是做一个合格的开发人员的基础。就像我们承认做人要诚实、有爱心一样。有时候文档是开发人员之间交流的主要媒介。这样，我们写作文档的目的就是用文字的形式表达自己，并且让读者最大限度的理解。所以，文档的写法的一个很重要的指导思想就是第一，最大限度地表达自己；第二，最大限度地让别人理解。

那么，开发人员的文档和其他行业的文档（例如政府报告）又不同。政府报告可以完全用本国的官方语言书写；而开发文档的特殊性在于，开发所使用的程序是基于英文的，而文档必须涉及大量的专用词汇。而技术文档也不等同于文学翻译，准确性不体现在把所有外语词都准确无误地译成英文。也不可能这么做。所以，书写开发文档就有一个中英文的选择问题，什么时候使用中文，什么时候使用英文，什么时候必须同时使用？

每个人在任何时候都有一个形象。念书的时候，成绩单就是你的形象；与朋友交往，言谈就是你的形象；而做为开发人员，文档有时候就是你的形象。文档可以在很大程度上反应一个人的面貌：你对你所从事的技术了解是否深入、你是否有足够的经验、或者你是否足够专业。书写文档不是说话，行文上要使用书面用语，而不能像“录口供”。当然，本文要讨论的是中英文的使用，但文法的准确是书写的基础。

中英文选择使用的意义

大多数技术名词都可以直接译为中文，但不是每种译法都能被所有人接受。我们通常把 Microsoft 叫做“微软”。但我们几乎在我们的中文版Windows里找不到“微软”这个词。在正式的产品里，Microsoft 都只称自己做 Microsoft。同样，Microsoft 也从来不把 Windows 称为“视窗”。而 Microsoft 的大多数产品都是没有中文名称的。这也许是一个极端的例子，但是已经可以说明问题：任何词汇的使用，都不是可以完全的中英文互换的。只可以在合适的环境使用合适的形式。

用以选择的原则

那么，是否有固定的原则可以遵循呢？答案是有的。简而言之就是：使用大多数人可以接受的形式，或者不会引起误解的形式。换句话说，即让你的读者可以立即判断出你要表达的概念，而不会误解为其他的东西。对于选用的规则，无非是：

1. 只使用英文形式
2. 中英文可互换
3. 只使用中文
4. 中英文需要同时使用

而具体对于选用的原则说来，可总结为如下：

1. 使用广大开发人员已经约定俗成的形式。例如“design patterns”, 相信大部分朋友都称作“设计模式”，那么就可以不用使用英文。类似的是“enterprise”，我们已经习惯称为“企业版”、“企业级”，就可以不用写出英文。
2. 使用官方或者权威机构所常用的形式。例如“architecture”，我们可以看到在MSDN的专栏，总是翻译为“体系结构”，那么我们就名正言顺地照抄，而不用担心有异议。而同样在MSDN，“.NET Framework”并没有译为“.NET 框架”。
3. 非技术词汇应避免使用英文。如果文档本身是使用中文书写的。那么不应该使用英文的地方就可以不用。应避免大段的中文中出现意义很简单的并且中文可正确表达的词或者句子。例如，我们说明文档的“版本”，就没有必要使用“version”或者“revision”；中文文档的“引言”部分，就没有必要使用“introduction”。
4. 翻译之后的词汇不可产生歧义。例如“Web Services”就尽量不使用“Web 服务”来表达。
5. 某些词虽然是由很常见的词汇组成的，但表示特定的含义，此时也不可以随意使用中文的直译。例如“Windows Update”，表示Windows 联机进行更新的服务，也不可用作“Windows 升级”或“Windows 更新”。
6. 某些词虽然单独使用有确定的中文含义，但与其他词的复合形式尚未广泛地应用，此时也不可以使用中文的直译。例如“XML Schema”，就不好用作“XML 模式”，不然会使别人的理解造成困难。这样的情况应该使用原有的形式。 类似的例子还有“HTTP module”和“HTTP handler”
7. 中文名称很长的，不应该使用中文形式。例如“HTML”，恐怕没有人用作“超文本标记式语言”。
8. 一些非技术词汇的英文的习惯用法，可以不翻译为中文。例如“best practices”，可以不必翻译为“最佳用法”，直接使用原形式更容易理解。相类似的情形还有刚刚流行起来还没找到合适的中文表示的英文词汇。例如“cutting-edge“等等。
9. 工程项目或者 SDK 专有的词汇的引用要避免一厢情愿地译为中文。有很多朋友写技术文档的时候把RequiredFieldValidator译为“非空验证器”，反而让人不知所云。开发环境的类名和其他专有名词都应使用其原有形式，包括大小写、name space在内。而“DropDownList”，也不能作“下拉列表”。还有非公共类库内的标识符的引用，比如我们使用“Employee”表示“员工”，在描述这个类时应使用“Employee类”而不应该使用“员工类”。而 interface Person 也不能描述为“人接口”。
10. 而开放环境中其他已经习惯使用的词汇就需要使用正确的中文形式，例如“build”作“生成”；“debug”作“调试”；project作“工程项目”。同时上述的情况应根据实际的开发环境而定。如果团队统一使用英文开发环境，则这些专用名词应作实际的形式。例如使用“check in”代替“签入”…
11. 一直在文档中出现的关键词汇，应在第一次使用时同时使用中英文形式。例如我们可以这样在文档中引入“每日构建(Daily Build)”。而具有缩写形式的词汇，应加上其缩写形式。例如Visual Studio 2005 Tools for Office（VSTO）。
12. 人名、机构名应使用其原有形式，为表达上的准确，一般不翻译为中文。包括大小写及字符的组合。例如“Microsoft .NET”、“iPod”、或者"World Wide Web Consortium (W3C)"。
13. 注意常见词汇的正确译法。例如 C# 环境内的过程（method），正确的叫法应该是“方法”而不是“函数”；property应该是“特性”或“属性”；

其他

除了注意中英文形式的选用外，英文的书写也要注意其形式。例如：

1. 中英文混排的空格。中英文混排时，如果不是使用像 Microsoft Word 这样自动处理中英文间隔的处理器，中英文之间应保持一个空格。
2. 注意使用完全、正确的英文形式。在正式的文档中，不应使用尚未约定俗称的缩写。例如“Visual Studio 2005”不应该写作“VS2005”。另外，提及其他厂商的产品时，应加上厂商名，例如IBM WebSphere，就比只使用WebSphere正式得多。
3. 禁止使用非法的书写形式。例如.NET虽然读作“dot net”，但不能写成“DotNet”。
4. 使用正确的单词复合形式及大小写形式。例如“SharePoint”、“InfoPath“是连在一起的而“Visual Basic”、 “Smart Tag“却是分开的。“Windows XP”的“XP”、“XML”及“.NET”是两个字母全部大写，而“Sun”、“Java”是首字母大写。这些都是厂商的商标或者习惯用法。另外，除了一些专有名词例如“Smart Client”使用每个单词首字母大写外，一般性的英文短语如“MSDN subscribers”应该保持小写、单词之间使用空格分开的形式，除非一个整句的开头是英文词。写错大小写是不专业的。
5. 使用正确的复数形式。表示复数意义的名词，绝大部分应用的时候是使用复数形式。例如“Utilities”，“Web Services”就不能作“Utility”，“Web Service”，意义是完全不一样的。
6. 使用正确地动词形态。只使用字典里查到的动词原形做复合词是很傻的。例如表示基于web的应用应该使用“web based application”而不是“web base”。表示“可校验的控件”应使用“validatable controls”而不是“validate control”。 即便是字典里找不到 validatable 这个词。
7. 除上述之外，还应该注意使用合适的缩写形式以及准确的用词。
8. 使用正确的标点符号。