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)
点击展开参考答案

答案3是最佳选择。尽管要保证代码的简短,但是省略掉参数会让新手无所适从。

注释

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

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

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

练习

下面范例代码的注释有什么问题?(假设该代码的受众是对brAPI不熟悉,但对“流”这个概念比较熟悉的程序员):

/* Create a stream from the text file at pathname /tmp/myfile. */
mystream = br.openstream(pathname="/tmp/myfile", mode="z")
点击展开参考答案

注释有以下瑕疵:

  • 对代码中不言自明的片段做解释。
  • 对代码不够清晰的部分反而没有解释。即,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.
点击展开参考答案

最佳范例集是答案1.提供不同难度的范例代码往往是最优选择,特别是对新手。新手想要看到的简单和中等难度范例代码。请控制想要跳过这些部分,而很快到复杂范例代码部分的冲动。

Reference

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

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

results matching ""

    No results matching ""