Creating sample code

好的代码范例往往是最佳的文档。即使你的段落和列表像海水一样清澈，程序员仍更喜欢好的代码范例。毕竟文字和代码是不同的语言，代码总是程序员最关心的东西。用文字来描述代码，就像是用英语来解释意大利诗歌一样。

好的代码范例是正确的、简洁的，读者可以快速理解、并用最小的力气重用它。

正确性

代码范例需要符合以下标准：

• 可以正确编译。
• 按照预期执行。
• 最好可以在生产中直接使用。例如，代码不应该有安全漏洞。
• 遵循编码规范。

代码范例是直接影响用户写代码方式的机会。因此，代码范例应该是使用产品的最佳方式。如果有超过一种代码写法，请用你的团队公认最佳的写法。如果你的团队还没有对比过各种写法的好处或坏处，请先做这件事。

请务必测试你的代码范例。随着时间的推移，代码可能因为系统的变化而不可用。请随时准备着测试和维护你的代码范例，就像你维护其他代码一样。

很多团队使用其单元测试程序作为其范例程序，这有时并不是一个好主意。单元测试代码的主要目的是测试，而范例代码的唯一目的是教会读者。

代码片段是一小段范例程序，往往只有有限的几行。代码片段过多的文档，往往随着时间的推移质量下降，这是因为团队一般不会测试像测试完整范例程序一样测试代码片段。

执行范例代码

好的文档会告诉读者如何执行范例代码。例如，你的文档可能需要告诉读者，必须执行如下动作后才能执行你的范例代码：

• 安装特定的库文件。
• 为特定的环境变量赋值。
• 修改IDE中特定的设置。

用户往往不会正确的执行这些前置动作。一些情况下，用户宁愿直接执行或实验性执行文档中的范例代码。

文档作者应该要描述范例代码执行的预期结果，特别是对那些不容易执行的代码。

简洁

范例代码应该简短，仅包括最核心的部分。当一个C语言新人想要学习如何执行malloc函数时，给这个新人一个简短的代码片段，而不是整个Linux源代码树。无关的代码会分散读者注意力，让读者迷惑。尽管如此，不要为了缩短而缩短，应该是正确优先，其次才是简短。

易理解

如何提供清晰的代码范例，如下是一些建议：

• 代码中的类、方法或者变量的名字应该体现其含义。
• 避免用一些难以理解的代码花招来迷惑读者。
• 避免深度嵌套的代码。
• 可选： 关键代码可以使用加粗和有颜色的字体标记，吸引读者的注意。但是请谨慎使用高亮，太多的高亮对读者来讲相当于什么也没有高亮。

练习

下面三个代码范例哪个更为有效？假设你的目标读者有对go.so这个API完全不熟悉的人。

1. MyLevel = go.so.Level(5, 28, 48)
2. MyLevel = go.so.Level(rank=5, 28, 48)
3. MyLevel = go.so.Level(rank=5, dimension=28, opacity=48)

注释

在代码范例中使用注释时，请考虑如下建议：

• 注释应该简短，但是总是清楚优于简短。
• 避免对有明显含义的代码做注释。但是记住对你这个专家含义很明显的代码，对新手则不一定明显。
• 将注释的精力花在不够直觉的代码上。
• 若你的读者对某个技术非常有经验，请不要解释代码正在做什么，而是解释代码为什么要这么做。

应该将代码注释放到代码内还是文档的文字部分（段落中或列表中）？注意，读者复制粘贴的代码不仅仅包含代码本身，也包含内嵌的注释。因此，请将代码的描述信息内嵌到范例代码中。相反，当你不得不解释一个很长或者很取巧的概念时，你应当将这些介绍放在范例代码前的文本中。

练习

下面范例代码的注释有什么问题？（假设该代码的受众是对brAPI不熟悉，但对“流”这个概念比较熟悉的程序员）：

/* Create a stream from the text file at pathname /tmp/myfile. */
mystream = br.openstream(pathname="/tmp/myfile", mode="z")

可重用

为了让读者可以方便地重用你的代码，请提供如下信息：

• 所有运行范例代码的资讯，包括一些前置条件和设定方法。
• 可以有效地扩展和客制化的代码。

使用可正确编译的、简洁的且易理解的代码是个不错的开始。如果代码让用户的APP崩溃，用户会崩溃的。因此，提供范例代码时，应该考虑代码被整合到其他地方的可能副作用。没人想要不安全或者效率极低的代码。

提供正面和反面范例

除了给读者展示应该做什么，有时也需要告诉读者不应该做什么。例如，许多编程语言允许程序员在等号前后增加空格。但现在假设你正在写一个编程语言指南（例如bash），该语言不允许等号前后加空格。这种情况下，同时提供正面和反面范例往往是不错的选择。例如：

[!TIP|label: 正面范例]

s="The rain in Maine."

[!DANGER|label: 反面范例,代码中有空格]

s = "The rain in Maine."

循序渐进

好的范例代码集应该难易都有。

毫无经验的读者希望简单的代码范例来起步。范例代码集合中最为基础的范例应该是“Hello World”. 掌握住基础后，工程师想要看到更复杂的范例。因此，好的范例代码集是循序渐进的，包括简单、中等和负责的范例程序。

练习

在一个介绍函数的手册中，下面哪个范例函数集是更好的？

1. 范例集1:
   1. A function that takes no parameters and doesn't return anything.
   2. A function that takes one parameter but doesn't return anything.
   3. A function that takes one parameter and returns one value.
   4. A function that takes three parameters and returns one value.
2. 范例集2:
   1. A function that takes three parameters and returns one value.
3. 范例集3:
   1. A function that takes one parameter and returns one value.
   2. A function that takes three parameters and returns one value.

Reference

原文：https://developers.google.com/tech-writing/two/sample-code