Short sentences

出于以下原因,软件工程师通常会尽量减少实现中的代码行数:

  • 较短的代码更容易他人阅读。
  • 较短的代码比较长的代码更容易维护。
  • 较长的代码往往会带来额外的Bug(做得越多错得越多)。

事实上,同样的规则也适用于技术文档写作:

  • 较短的文档比较长的文档阅读速度更快。
  • 较短的文档比较长的文档更容易维护。
  • 额外的文档段落可能会带来额外的错误。

将文档修改得最短需要时间,但是这是完全值得的。短句子比长句子更有表达力,也更容易理解。

一句话专注一个观点

一个句子请专注一个观点、想法或者概念。就像程序的语句只执行一个任务一样,文档的一个语句应该仅表达一个观点。例如,下面这个很长的句子包含多个想法:

The late 1950s was a key era for programming languages because IBM introduced Fortran in 1957 and John McCarthy introduced Lisp the following year, which gave programmers both an iterative way of solving problems and a recursive way.

将这个长句子分解成一系列单一想法的短句,得到如下结果:

The late 1950s was a key era for programming languages. IBM introduced Fortran in 1957. John McCarthy invented Lisp the following year. Consequently, by the late 1950s, programmers could solve problems iteratively or recursively.

练习

将下列过长的句子转换为一系列短句。不要修改太多,仅将句子拆成多个短句。

In bash, use the if, then, and fi statements to implement a simple conditional branching block in which the if statement evaluates an expression, the then statement introduces a block of statements to run when the if expression is true, and the fi statement marks the end of the conditional branching block.

点击展开答案

In bash, use an if, then, and fi statement to implement a simple conditional branching block. The if statement evaluates an expression. The then statement introduces a block of statements to run when the if expression is true. The fi statement marks the end of the conditional branching block. (The resulting paragraph remains unclear but is still much easier to read than the original sentence.)

将长句转换为列表

许多冗长的技术文档语句,亟待被拆分成列表形式。例如以下句子:

To alter the usual flow of a loop, you may use either a break statement (which hops you out of the current loop) or a continue statement (which skips past the remainder of the current iteration of the current loop).

当你在长句中看到连词or,请考虑使用项目符号列表来重构句子。如果你在长句中看到内嵌的任务列表,请使用项目符号列表(bulleted list)或有序列表(numbered list)来修改句子。例如,前面的示例使用了连词or,所以我们将这个长句转换为项目符号列表:

To alter the usual flow of a loop, call one of the following statements:

  • break, which hops you out of the current loop.
  • continue, which skips past the remainder of the current iteration of the current loop.

练习

使用列表将下面的句子重构得更短更清晰。

  1. To get started with the Frambus app, you must first find the app at a suitable store, pay for it using a valid credit or debit card, download it, configure it by assigning a value for the Foo variable in the /etc/Frambus file, and then run it by saying the magic word twice.
  2. KornShell was invented by David Korn in 1983, then a computer scientist at Bell Labs, as a superset of features, enhancements, and improvements over the Bourne Shell (which it was backwards compatible with), which was invented by Stephen Bourne in 1977 who was also a computer scientist at Bell Labs.
点击展开答案

Sentence 1

Take the following steps to get started with the Frambus app:

  1. Find the app at a suitable store.
  2. Pay for the app using a valid credit or debit card.
  3. Download the app.
  4. Configure the app by assigning a value for the Foo variable in the /etc/Frambus file.
  5. Run the app by saying the magic word twice.

Sentence 2

The following two Bell Labs computer scientists invented popular shells:

  • Stephen Bourne invented the Bourne Shell in 1977.
  • David Korn invented the KornShell in 1983.

The KornShell is a backwards-compatible superset of the Bourne Shell, containing many improvements over the older shell.

去除或减少无关单词

许多句子包含了一些填充词,它们是毫无营养又占用空间的“文本垃圾”。你是否可以在如下例句中找到不必要的单词:

An input value greater than 100 causes the triggering of logging.

causes the triggering of logging改为更短的动词triggers,使句子变得更短:

An input value greater than 100 triggers logging.

通过练习,你将会发现多余的单词,并体会到删除它们带来的巨大愉悦感。例如:

This design document provides a detailed description of Project Frambus.

句子中 provides a detailed description of 可以修改为动词 describesdetails。因此修改后的句子如下:

This design document describes Project Frambus.

下表呈列一些常见臃肿语句的建议修改方法:

Wordy Concise
at this point in time now
determine the location of find
is able to can

练习

在不修改语义的前提下将下列句子变短:

  1. In spite of the fact that Arnold writes buggy code, he writes error-free documentation.
  2. Changing the sentence from passive voice to active voice enhances the clarification of the key points.
  3. Determine whether Rikona is able to write code in COBOL.
  4. Frambus causes the production of bugs, which will be chronicled in logs by the LogGenerator method.
点击展开参考答案
  1. Although Arnold writes buggy code, he writes error-free documentation. 还可以是: Arnold writes buggy code. However, he writes error-free documentation.
  2. Changing the sentence from passive voice to active voice clarifies the key points.
  3. Determine whether Rikona can code in COBOL.
  4. Frambus produces bugs, which the LogGenerator method logs.

去除从句(Optional)

从句是一个句子中独立的逻辑单元,包含了一个主语和一个谓语。每个英文语句都包含以下内容:

  • 一个主句
  • 0个或者多个从句

从句修饰主句。顾名思义,从句不如主句重要。例如,考虑如下句子:

Python is an interpreted programming language, which was invented in 1991.

  • 主句: Python is an interpreted programming language
  • 从句: which was invented in 1991

通常可以通过引出它们的词来识别从句。如下列表不完整地显示了引入从句的常用词:

  • which
  • that
  • because
  • whose
  • until
  • unless
  • since

有些从句以逗号开头,有些则没有。下例中高亮的从句由because引入且没有逗号:

I prefer to code in C++ because I like strong data typing .

修改时,始终坚持一句话阐述一个观点,仔细检测从句。从句是否只是对主句观点的引申,还是分支成新的观点?如果是后者,请考虑将有问题的从句拆分成独立的句子。

练习

确定下面句子中哪些包含从句,以及哪些从句应该要拆成独立的句子(不要重写句子,只需要判断其是否需要重写即可)。

  1. Python is an interpreted language, which means that the language can execute source code directly.
  2. Bash is a modern shell scripting language that takes many of its features from KornShell 88, which was developed at Bell Labs.
  3. Lisp is a programming language that relies on Polish prefix notation, which is one of the systems invented by the Polish logician Jan Łukasiewicz.
  4. I don't want to say that Fortran is old, but only radiocarbon dating can determine its true age.
点击展开答案

将从句高亮

  1. Python is an interpreted language, which means that the language can execute source code directly . 从句只是对主句的引申,因此不用修改
  2. Bash is a modern shell scripting language that takes many of its features from KornShell 88 , which was developed at Bell Labs . 第一个从句是主句的引申,第二个从句则表达了新观点,需要拆成两个句子.
  3. Lisp is a programming language that relies on Polish prefix notation , which is one of the systems invented by the Polish logician Jan Łukasiewicz . 第一个从句明显对句子至关重要,但是第二个从句则不然,需要拆成两个句子.
  4. I don't want to say that Fortran is old, but only radiocarbon dating can determine its true age. 这个从句对句子至关重要,因此可以不动.

区分that和which

Thatwhich都会引出从句。它们的区别是什么?好吧,在某些国家,这两个词几乎可以互换。不过,警惕的美国读者不可避免地会愤怒地宣布,你又把这两个词弄混了。

在美国,which用于引出非必要的从句,而that引出的是对句子必不可少的从句。例如,下面句子中的关键信息是“Python是一种解释性语言“,如果没有Guido van Rossum invented也是成立的。

Python is an interpreted language, which Guido van Rossum invented.

反之,下面例句中don't involve linear algebra是必不可少的:

Fortran is perfect for mathematical calculations that don't involve linear algebra.

如果你大声朗读一个句子,并在从句前听到停顿,那么which是你的不二选择。反之,选择that。返回并朗读一下上面的两个例句,在第一个句子中听到停顿了吗?

Which前需要加逗号,而that前不需要

Reference

原文:https://developers.google.com/tech-writing/one/short-sentences

Copyright @ Lambert 2022 all right reserved,powered by GitbookModified Time: 2024-02-24 14:20:10

results matching ""

    No results matching ""