不想做写作大师的程序员不是好码农

白痴小菜

[indent,全文共2930字，预计学习时长10分钟
[/indent, 图源：Pexels 摄影：StartupStock Phot

自《Better Programming》出版以来，我一直在其中做文字编辑工作。据我的经验看，程序员都是相当不错的作家。
当然，出于工作原因，我编辑过许多文章。我觉得如果不能用多种方法来改善原文，便没有工作的感觉。然而，就算程序员的文章有许多语法错误，文章的框架和组织结构仍十分出彩。显然，计算机语言的知识为英文写作提供了更为逻辑系统的方法。
话虽如此，程序员还是经常会在写作的一些点上遇到问题。


程序员和读者的关系是什么？
相对读者而言，不同的写作类型要求作者有不同的身份定位。例如：在案例研究里，是讲师；编写教程时，是向导；在评论文章中，是读者的朋友；而撰写报告时，又是记者。
用以下四个句子举例：
· “Next, we’ll take a look atmulti-node Kubernetes clusters.（接下来，让我们看一下Kubernetes多节点集群。）”
· “Next, you’ll look atmulti-node Kubernetes clusters.（接下来，您将看到Kubernetes多节点集群。）”
· “Now, I’ll take a lookat multi-node Kubernetes clusters.（现在，我来看一下Kubernetes多节点集群。）”
· “Now, take a look atmulti-node Kubernetes clusters.（现在，看一下Kubernetes多节点集群。）”
这些句子本身并无语法问题，但每句话都对读者提出了不同的阅读期望。
“（Next, we’ll take a look atmulti-node Kubernetes clusters.）接下来，让我们看一下Kubernetes多节点集群。”
“we（我们）”是第一人称复数，此时，作者便成为了读者的阅读向导，是整篇文章的引导者。这种口吻在教程、指南编写中很常见。
我注意到有些作家在文章中会用“我们（we）”引导读者阅读，后来的每一个名词都用物主代词“我们的（our）”进行修饰。比如，“Next we open up our dashboard…then we click on our submitbutton …now we’ve come to the end of our project.（接下来，打开我们的仪表板...然后单击我们的提交按钮...现在已经到了我们的项目结尾。）”或许在编程里，每提到一个名词时，必须指明其所有关系，然而在英文写作中并非如此！即使某段文字里用了“我们”或“让我们”，后面的名词也可以随时恢复使用默认定冠词“ the”来修饰名词。
“Next, you’ll look at multi-node Kubernetes clusters.（接下来，您将看到Kubernetes多节点集群。）”
这里使用了第二人称单数的将来时态。在这句话中，作者不再是阅读的参与者（因为第一人称“我们”包括作者和读者，而“您”仅仅包括读者），这让文章阅读起来没有那么亲切，只是单纯让读者知道了他想了解的的事实而已。
“Now, I’ll take a look atmulti-node Kubernetes clusters.（现在，我来看一下Kubernetes多节点集群。）”
这里使用了第一人称单数的将来时态。这样就把读者从文章阅读结构里剔除出来，仅仅留下了作者一个参与者。这使得文章成为作者自己的故事，而读者只是被动的接受者。这种语调并不适用于编写教程或指南，因为这种情况下需要使读者有参与感。然而，这种语调非常合适编写技术报告或会议报告。
“Now, take a look at thesemulti-node Kubernetes clusters.（现在，看看这些Kubernetes多节点集群。）”
这句话是命令式。径直地告诉了读者要做什么，因此读者可以主动接受信息。编写教程时，您需要告诉读者要做什么、怎么做，因此最好使用命令式。当然，当您期望读者检查文章里的图表或某些代码时，也可以使用命令式。
我的建议是：始终如一。动笔前要决定身份定位—对于读者而言，您究竟是向导、讲师、有趣的朋友、故事叙述者，还是操作指导。写作时一定要牢牢遵循自己的身份定位。


多余的语法冗余
这个标题就是典型的语法冗余。为什么？根据定义，语法冗余已经包含了多余的意思。从这里可以看出，“语法冗余”的涵义是：使用多余的文字来表达同样的意思。
您也可以将其理解为语言赘余（只是这种叫法不太合适，因为听起来过于夸张）。
其实，冗余在英语口语和书面语中很常见。编程里也有冗余。维基百科给冗余代码下了定义：
Incomputer programming, redundant code is source code orcompiled code in a computer program that is unnecessary, such as:
recomputinga value that has previously been calculated and is still available,
codethat is never executed (known as unreachable code)]
codewhich is executed but has no external effect (e.g., does not change the outputproduced by a program; known as dead code).
（ “计算机编程的冗余代码是计算机程序不必要的源代码或编译代码，例如：
重复计算的可用值，
永远不会被执行的代码（无法访问的代码），
可以执行但无法影响外部环境的代码（例如，不能更改程序输出的代码；这也称为无效代码）。” ）
如果将英语视为人类的代码（这是事实），其输出则是语言接受者的理解程度。冗余增加了文章字数，却无法提高读者对文章的理解。
就像在计算机语言里，如果删除某行代码后还能保持相同的输出，则该代码行是多余的，应该删除。
一些冗余例子
“Similarly, their interactive visualizations also comewith simple explanations.（类似地，交互可视化的解释也同样很简单。）”可以删除“类似地”或“同样”。因为这两个词在句子中执行相同的功能，都表示与上文出现的物件相比较。
“When Ifirst started using JavaScript Promises I thought they were magic.（当我第一次开始使用JavaScript Promises时，我就觉得它非常神奇。）”“first（第一次）”和“started（开始）”意思重复了：您第一次做某事，就是开始做某事。这句话应该改成“When I started using…（当我开始使用······）”或“When I first used….（当我第一次使用·····）”。
“许多次（many times）”可以改成“经常（often）”。
“非常多（a large number of…）”可以改成“很多（many）”。
“为了去（in order to）”可以改成“去（to）”。
“Utilize”和“use”的意思都是“使用”，文章里用“utilize”不会看起来更聪明，何况它还浪费了两个音节！（实际上这不是冗余，只是个人见到会头痛。请不要再用“utilize”了。）
偶尔的冗余也不是大问题。如果见到有人写“一刻的时间（a moment in time）”（所有“时刻”都是“在时间里”的！！！）我也不会抓狂。
但是，大量的冗余会使写作冗长得毫无意义、令人生厌，甚至使文章更费解。
好文章和好代码一样，需要有效精简。


代码格式
我是一名编辑，不是程序员，因此在格式化代码上帮不上什么忙。而如何将代码整合到文章里却关乎格式和措辞的问题，这就是我的工作了。对此我有一些建议。
《Better Programming》有个简单的教程，专门指导作者如何将代码整合成一个句子：将代码夹在两个重音符号“`”（这个键在多数键盘Esc键下方）之间，您的代码会这样显示。
如果您用了其他格式编写代码-像这样或这样-我们会帮您修改格式。但是，无论您用哪种格式，请至少保持一致，这样可以减少出错率。
如果格式不一致，我们便无法区分函数和函数名称。换句话说，我们便无法区分Swift（一项技术）、. swift（一种后缀）和swift（一种鸟或表示“快速”的形容词）。
长代码块
通常，长代码块（多于两行）应放在Gist里面。然而， Gist目前无法在Medium上正确渲染。因此，即使对于长代码块也请使用此样式：段落开头打三个重音符号,这样可以对整个段落进行格式化。
注意，请勿将长代码段当成句子的一部分。不要这样写：
现在，打开文件并添加
*多行JavaScript代码 *
最后……（接上句）
事实上，在仅有单个术语或短代码行的情况下才能将其整合为一个句子。您可以适当引入长代码段，但要这样写：
现在，打开文件并添加以下代码：
*多行JavaScript代码 *
（新句子……）


后记
我们对《Better Programming》的内容持积极采纳态度。想法才是最重要的。如果我们认为您的内容有价值-满足当下需求且为原创内容-我们将十分乐意为此投入精力，让好文章被更多人看到。




留言点赞关注
我们一起分享AI学习与发展的干货
如转载，请后台留言，遵守转载规范