全文共2930字，预计学习时长10分钟
图源：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学习与发展的干货
如转载，请后台留言，遵守转载规范
本文来自投稿，不代表本人立场，如若转载，请注明出处：http://www.souzhinan.com/kj/271334.html