Punctuation(Optional)
本可选单元对标点符号做一个快速复习。
逗号
编程语言对符号有着明确的强制规则。相比之下，在英语中，关于逗号的使用规则却有些模糊。简单的指导方针是，在一句话中读者会自然停顿的任何位置加上逗号。用音乐的术语讲，如果句号是全音符休止符，那么逗号可能是半音符或四分音符休止符。换句话说，逗号的停顿短于句号。例如，如果大声朗读以下句子，你可能会在单词just前做简短停顿：
C behaves as a mid-level language, just a couple of steps up in abstraction from assembly language.
有些情况是必须使用逗号的。例如，逗号作为内嵌列表项目的分隔:
Our company uses C++, Python, Java, and JavaScript.
你可能会想，上面例句中，列表的第N-1和第N项之间的最后一个逗号是否应该存在。这个逗号( 叫做serial comma或者Oxford comma )是有争议的。我们建议机上这个逗号，单单是因为技术写作需要选择最不容易造成混淆的方案。尽管如此，我们实际上更倾向于使用项目符号列表而不是内嵌列表，以此规避争议。
在条件状语从句中，应当使用逗号来区隔条件和结果。例如，如下两句中逗号的使用都是正确的：
If the program runs slowly, try the
--perfflag.If the program runs slowly, then try the
--perfflag.
你也可以使用两个逗号对名词做快速的定义或解释，例如：
Python, an easy-to-use language, has gained significant momentum in recent years.
最后，避免使用逗号来连接两个各自独立的想法。例如，如下句子使用逗号做分隔，犯下了“逗号分隔重罪”（comma splice）。
[!DANGER|label: Not Recommended]
Samantha is a wonderful coder, she writes abundant tests.
应使用句号而不是逗号来分隔两个独立的想法。例如：
[!TIP|label: Recommended]
Samantha is a wonderful coder. She writes abundant tests.
练习
在下列段落合适的位置添加逗号：
Protocol Buffers sometimes known as protobufs are our team's main structured data format. Use Protocol Buffers to represent store and transfer structured data. Unlike XML Protocol Buffers are compiled. Consequently clients transmit Protocol Buffers efficiently which has led to rapid adoption.
提示：大声朗读句子，在听到简短停顿的位置增加逗号。
Protocol Buffers, sometimes known as protobufs, are our team's main structured data format. Use Protocol Buffers to represent, store, and transfer structured data. Unlike XML, Protocol Buffers are compiled. Consequently, clients transmit Protocol Buffers efficiently, which has led to rapid adoption.
分号
句号分隔不同的想法; 而分号将高度相关的想法连接起来。例如，请注意以下句子中的分号如何将第一个和第二个想法结合起来的：
[!TIP|label: Recommended]
Rerun Frambus after updating your configuration file; don't rerun Frambus after updating existing source code.
使用分号前问问自己，如果将分号前后的子句交换，是否仍能读得通。例如，前文做如下修改仍是有效的：
Don't rerun Frambus after updating existing source code; rerun Frambus after updating your configuration file.
分号前后的子句在语法上应该仍是完整的句子。例如，如下句子中分号后的句子是一个从句而不是完整的句子，因此这里分号的使用是不正确的：
[!DANGER|label: Not Recommended]
Rerun Frambus after updating your configuration file; don't rerun Frambus after updating existing source code.
应该改为：
[!TIP|label: Recommended]
Rerun Frambus after updating your configuration file, not after updating existing source code.
正如本课程之前所提，技术文档写作通常更倾向于使用项目符号列表而不是内嵌列表。然而，如果你一定要用内嵌列表，请使用逗号而不是分号分隔项目项目。例如：
[!TIP|label: Recommended]
Style guides are bigger than the moon, more essential than oxygen, and completely inscrutable.
许多句子会在分号后放一个过渡词或短于。这种情况下，转接词或短语后应该跟一个逗号。例如：
Frambus provides no official open source package for string manipulation; however, subsets of string manipulation packages are available from other open source projects.
或者：
Even seemingly trivial code changes can cause bugs; therefore, write abundant unit tests.
练习
如下句子哪些句号或者逗号要被替换成分号？
- Python is a popular programming language. The C language was developed long before Python.
- Model learning for a low value of X appears in the top illustration. Model learning for a high value of X appears in the bottom illustration.
- I'm thankful for my large monitor, powerful CPU, and blazing bandwidth.
- 不能换成分号，因为这两句话关联性不强。
- 可以将第一个句号换成分号，因为这两句话关联性很强。
- 因为是内嵌列表，需要用逗号而不是分号分隔。
Em破折号(Em-Dashes)
Em破折号是引人注目的标点符号，使用上有着丰富的可能性。Em破折号代表着比逗号更长的停顿--一个更长的中断。如果逗号是四分音符休止符，那么Em破折号就是二分音符休止符。例如：
C++ is a rich language—one requiring extensive experience to master.
文档作者有时使用一对Em破折号来包住“题外话”，例如：
Protocol Buffers—often nicknamed protobufs—encode structured data in an efficient yet extensible format.
前文示例中可以使用逗号来代替Em破折号吗？当然可以。那为什么还要使用Em破折号呢？感觉、艺术、经验。
En破折号(En-dashes)和连字符
看下表中的水平(horizontal)标点符号：
| Name | Mark | Relative width |
|---|---|---|
| em-dash | — | 最宽(一般和字母m等宽) |
| en-dash | – | 中等 (通常和字母n等宽) |
| hyphen | - | 最窄 |
在一些特定用法中，有些写作风格指南会推荐使用en-破折号。但是Google Style Guide提供了直截了当的建议如下：
不要用它。
连字符(hyphen)则有点难办。在技术文档写作中，连字符要作为复合单词的连接符，例如：
- self-attention
- N-gram
令人疑惑的是，三个词以上组成的复合词，通常会在第一个和第二个词中间增加连字符，而不是在第二个和第三个词中间。例如：
- decision-making system
- floating-point feature
若对连字符的使用有疑惑，请查找字典、词汇表或写作风格指南。
[!Note]
如果你查阅不止一本关于连字符的字典、词汇表或者写作风格指南，你可能会碰到不同的说法。
括号
将次要观点或者与主题相关性不大的内容放到括号内。括号告诉读者，其内的文字不并不重要。因此有些作者认为，括号内的内容甚至不应该出现在文档中。作为折中，技术文档应该最小限度地使用括号。
句点和括号同时出现时的相关规则一直不是很明确。如下是标准规则：
- 如果括号内包含完整的句子，句点应该放在括号内。
- 如果括号是句子的结尾，但不包含整个句子，句点应该放在括号外。
例如：
(Incidentally, Protocol Buffers make great birthday gifts.)
Binary mode relies on the more compact native form (described later in this document).
Reference
原文: https://developers.google.com/tech-writing/one/punctuation