程序员的文档调优(一):基本守则

撰写代码是程序员的本职工作,但编写文档时至今日依然常常遭到忽视。纵有高人曰过,优雅的代码是最好的文档,但先不说多少人的代码能达到这般境界,许多事务并不能仅靠代码本身完成。例如:用户文档,不能倚赖用户去阅读代码后再使用你的系统;设计文档,需要快速纵览项目时并无闲暇去阅览数万行代码;需求文档,乙方不可能按着你的 API 接口声明猜测你的意图……然而,几乎每一个程序员都被文档的匮乏深深伤害过。

于是,许多意识到重要性的程序员开始着手编写文档了。可惜的是,编程与语文这两项技能似乎常常互不兼容。大量程序员的写作水平不尽人意,写出的文档也不堪卒读,让人或云里雾里,或视觉疲劳。最坏的情况是看了还不如没看——有错误的地图甚至坏过没有地图。每次面对比遗留代码还深奥的文档时,我都感觉自己又在折寿。

是程序员的大脑普遍缺乏语文神经吗?私以为,还是十二年中小学语文教育以分数为导向、缺乏实用的「语文技能」教学所致。语文课堂上,为了分数,学生被灌输的是「鉴赏」(其实就是模式识别加套路背诵)和「写作」(其实就是八股文加更多的套路背诵)。在阅读理解中,学生读懂出题者的意图,投其所好;到了写作里,学生搜肠刮肚,将一堆名人名言砌入起承转合。选择程序员为职业的人,多数本就缺乏诗词歌赋的天赋,再加之从未习得(实用的)写作技能,自然难以奢望在真实环境里有何等写作能力。

扯得有点远,但我想说的是,适用于真实写作的实用技能是存在的(也可以称之为有用的套路)。尤其是对于并不要求多少创造力的各类程序文档而言,能够简洁、明了、完整、优雅地表达意图,便已实属优秀了。

我自认语文能力算不得优秀,但还算从各路捡到过一些技巧;加之作为程序员,在一年的实习里就已见到太多惹人揪心的文档。于是我想在此分享一些程序文档写作的技巧与经验,就当是抛砖引玉。如贻笑大方,还请多加指教、手下留情。

在此先说明一下这些方法的总目的:

  1. 优雅美观。好的文档应当赏心悦目的,从排版至字里行间流露严谨而可靠的气质。
  2. 平易近人。好的文档读起来应该是高效而不累的,即无繁冗的词句,也没有晦涩的字词。
  3. 清晰明了。好的文档要组织清晰,将符合使命的信息完整地传递给目标用户。

另外,为预防一些歧义,需要在此声明一下适用范围:

  1. 仅适用于电子书面文档。口头交流、IM 沟通、纸张书写因其不同特性,并不建议直接套用本系列文章中的所有方法。
  2. 仅适用于正式的说明文。文艺创作是一个复杂的领域,我不敢班门弄斧,也不愿让固化的套路破坏文学的优美。

这篇文章里,我们先来看看我认为最重要的那些守则。这些守则提纲挈领,或可普遍适用。

排版

推荐文档:《中文文案排版指北》

内文排版是安排字词段落的艺术设计,对于书写文档的程序员而言,发挥的余地其实不多:我们编写文档的环境通常并不允许我们微调行间距、页边距等微妙的属性。

但即使是纯文本的写作环境下,依然有一组排版原则值得每一位写作者遵循。这组原则被诸多文章解释得颇为清晰,本博客不愿重复网上能轻易搜到的东西,所以烦请转至上方链接观看这篇我认为相对阐述到位的指引。

其实这组规范许多人早已有所耳闻,可能也学习过,但并不总是记得运用,或是不能适当地使用。知其所以然,方能运用自如。因此在这一节,我将介绍一下自己对某些规范的理解。

留白

加空格,或许是这套规范中最著名的一条。程序员可以分为两类,一类会在全半角词语之间加空格,另一类不会。其实与诸多规则一样,加空格不是目的,只是实现留白的一种手段,而留白的目的,又是为了美观易读。

在罗马字母书写的语言中,空格是非常常见的分词工具(八卦一下,欧洲直到八九世纪才在书写中普遍使用空格)。这一书写规则很好理解:避免歧义的同时,还能突出显示单词的形状(拼音语言单词的辨识度常来自于其边缘形状)。

而汉字,因其历史原因(如文言文中通常一字一词),从未引入空格等分词符。于是在中英混排时,就会出现一个疑问:不分词的中文和分词的英文之间,该不该加入分词符呢?

应当与否,这点早已有所定论。只要看看 Office Word 默认的排版引擎便知:即使是上古 Word,也会在全半角词语间自动加入空白间隙。而翻阅一些上世纪的老书,也能看到这样的痕迹。在我看来,适当的留白有助于语言思维的切换,也是对西文以空格分词的惯例的遵循,同时留白让挨着中文的单词相对独立,也更易辨读。

在中英之间加入适当的间距会提升可读性,这几乎是公认的。但如果仔细观察,会发现 Word 与书籍的排版中,留白并没有达到一个空格的长度,而是略短一点。是的,这才是混排留白的最佳距离,而加入空格来实现留白,不过是排版引擎不争气,写作者迫不得已的越俎代庖——但还是好过完全没有间隙。

非专业文字处理的排版引擎几乎都不会自动留白,这一点被人诟病已久,但我们确实可以看到进步的希望:Apple 最新的系统应用已经支持在中西文间自动留白,CSS 利用 text-spacing 属性指定留白规则也已进入提案,部分 app 如微信还自研了一套排版引擎实现这一特性(虽然经常爆出溢出漏洞)。

留白本应是排版引擎的事,但在其普及之前,还是给英文和数字的两端加上空格吧。

一致

一致性可以分为两类:标点符号与文章语言一致、专有名词与官方形式一致。

标点符号一致,要求写作者在中文文章中不使用半角符号,除非是整句地引用。而专有名词一致,则要求写作者使用官方的拼写和大小写形式,比如某知名交友网站要写作 GitHub,而非 github、Github,更不能是 gh。(说实话,我很少看到能拼对 GitHub 的程序员。)

这一套规范看似繁琐,但实际上对整篇文档的「气质」相当重要,一旦遵守,就能极大提升读者对文章及其作者的第一印象。一篇标点错乱、大小写涣散的文章,会在直觉上给人极不专业的感觉;而标点严谨,专有名词使用考究的文章,会自然而然地流露出正式、可靠的气息。

这一点,我时常在别人问我简历或者 PPT 的改进之处时指出。对于程序员而言,简历是用来体现自己专业技能和严谨态度的迷你文档,HR 和历位面试官对你的第一印象都来自于它。PPT 与之相仿,往往用于展示成果或推销想法,目的也是为了让观者接受其内容。在诸多场景中,正确的标点与拼写形式能彰显作者严谨可靠,也会随之提升内容的可信程度。

一致性是对形式的追求,但别人对内容与你的直观印象往往来自形式。

语法

文档里自然语言的语法错误,就像粥里的一颗沙子,咬到总会膈应一下。中学语文教学还是有用的,至少其病句修改能给我们建立汉语语法的初步印象,可惜完整语法就毫无立足之地了。尽管没有婴儿学说话前要先学语法,但作为写作者——文字内容的创造者,还是需要明确了解一些语法知识来指导我们的遣词造句的。

语法的掌握非一日之功,尤其是离开课堂以后,更难有动力与时间研究一门语言的形式(哪怕是自己的母语——但这也许更增进了虚假的自信)。其实,在病句题中学到的知识已经足以应对大部分的语法错误,只需要对自己写出来的东西多加回顾,诸如主语缺失一类的错误也不难改正。虽然语法基础是写作的重要技能,但本系列并不会详细讲解。

相比语法错误,更常见的是一些算不上错的语法问题,但这些问题会导致生硬的表达方式。这些问题多半是学习外语所致:在成长过程中,我们的老师很少会传授汉语语法(我有幸遇到了两位愿意讲解的语文老师,在此感谢他们),却在英语课上大量灌输异国他乡的句子成分、短语构成。不少人会在潜意识里将英语的语法知识迁移到汉语的空白中,造就了所谓的「英式中文」,写出来的东西繁琐别扭,不够流利自然。这类问题会在后续的文章中详加阐述。

审丑

这一点针对的不是文档,而是每一名作者自身。不懂得美的人无法创作出美,不懂得丑之所以为丑的人,也很难避免制造出丑。知道什么丑陋、为何丑陋,学会对之憎恶并试图改进,而不是漠然无视,才能让所创作之物趋于「美」。

审丑的第一步,是知丑为丑。比如看到一篇千疮百孔的文档,里面充斥着中英乱排、颠三倒四,我们要知道这篇文档是丑的;看到一个句子主语缺失、标点错乱,我们要知道这句话是丑的;看到某个单词大小写紊乱,我们要知道这个词是丑(至少不美)的。只有知丑为丑,我们才不会对房间的大象视若无睹,放任其继续存在。

审丑的第二步,是知丑为何为丑。其实大部分的丑,我们都能凭直觉感知,却难以清晰认知。某句话读起来怪怪的,但为什么呢?如果缺乏一套规则和理论,我们很难从感性认识提炼出理性知识,遑论改进与避免的方法。下次可能重复一样的错误,却不知结症何在、如何是好,最后也只能放任自流。倘若我们知其为何丑陋,便能有意识地避而远之。

不仅文档如此,编写代码也是相似的道理。没有完美的代码,每一个项目在生长过程中都会不可避免地滋生异味(code smells)。如果是一名对各类代码异味、反模式毫无知觉的程序员,可能根本无法意识到代码中的种种问题;或许能从程序运行的表象中发现一些迹象(如运行缓慢、修改代码困难),却不知根源所在。但如若了解各种代码的丑陋,并知其为何腐臭之后,我们便能对症下药,用谨慎避免新坑,以重构消化存量,而不是继续无知地在布满焦油坑的丛林里乱撞。

没有认知就难以思考,也无从应对。我不仅希望本系列短文能种下一颗强迫症的种子,还能介绍一番文档里常见丑陋之处。这样,下次看到(或不小心写出)这样的瑕疵时,就能够心想「噢,这里这么改会变得更好」。

发表评论

您的电子邮箱地址不会被公开。 必填项已用*标注