代码示例样式指南

本文档介绍了如何在文档中纳入代码示例，并介绍了代码示例的具体样式指南。其中包括：

• 代码示例最佳实践
• 代码示例核对清单
• 代码示例样式指南

如需了解常规文档标准（包括文件类型、位置和常规色调），请参阅 Fuchsia 文档标准。如需有关字词选择、样式和结构的具体指南，请参阅紫红色文档样式指南。

代码示例最佳实践

为您非常熟悉的 Fuchsia 部分创建代码示例时，请考虑新用户如何阅读该示例并尝试预测其需求。全面考虑整个流程，包括完成该流程的必要步骤，并指定对成功的标准。

例如，在开始使用代码示例之前，请考虑所有需要提供的信息。确保您没有忽视使用示例所必需的信息，但您的日常工作流中已不存在这些信息。

这可能是因为您执行这些步骤的次数过多，导致这些步骤不再是该过程中的必要步骤。这也可能是因为这些前提条件信息只需要填写一次，导致您在编写文档时无法回忆起这些步骤。如果可能，请尝试从头开始运行示例，并验证您已记录所有前提条件信息。

同样，请务必告知用户他们何时已成功完成给定过程。为提高用户对样本的信心，请务必指定用户代码的内容，以及用户如何确认他们已成功运行您的样本。

代码示例核对清单

如果您要在文档中添加代码示例，请在提交贡献内容之前查看以下列表，以确保代码示例清晰明了：

• 加入“前提条件”部分，将其作为文档的第一部分。 在用户启动该流程之前，在文档中收集前提条件信息，可防止用户受到不必要的屏蔽或沮丧。
  • 前提条件信息可包括以下任一项：
    • 修改环境变量。
    • 在开始该过程之前运行必要的脚本。
    • 获取设备访问权限。
    • 包含 BUILD 依赖项。
    • 导入库。
• 现有文档的链接（如适用）。 例如，您要记录的进程的前提条件可能是已铺砌的 Fuchsia 目标设备。 请不要重复说明如何铺路设备，而是链接到 fuchsia.dev 上已存在的现有“Pave”主题，例如 Build and pave quickstart（构建和铺路快速入门）。
• 如果您要在代码示例中包含占位符，请避免使用 foo、bar 或其他模糊的占位符名称。请改为使用能够表达代码中相应占位符函数的名称。如需了解详情，请参阅避免使用模糊的占位符。
• 通过陈述显而易见的方法将开发者锚定到流程中。 预料到有人可能没有通读您的文档就运行代码示例。因此，请确保您的代码示例具有空间感知能力。如需了解详情，请参阅指定展示位置。
• 以代码示例摘要的形式结束部分，其中详细说明了在过程的某个特定时间点完成后的代码应该是什么样子。如需了解详情，请参阅指定展示位置和确认成功。
• 描述测试过程所需的步骤，并显示成功的终端输出。

代码示例样式指南

下面介绍了在文档中创建易于理解的代码示例的切实可行的最佳做法。

避免使用不明确的占位符

代码示例占位符名称和值应在代码中表示其用途，避免使用 foo 和 bar 等抽象占位符。

• 使用占位符名称来表达该代码中占位符的函数。这样做可以为开发者提供一个真实的示例，供以后参考。

• 代码示例应该能够复制到终端中，并在无需用户进行大量更改的情况下成功运行。

请参阅以下示例，了解如何避免使用模糊占位符。

示例

protocol: "fuchsia.example.Foo"

  use: [
    {
      protocol: "fuchsia.process.Launcher"
    }
  ]

指定展示位置

代码示例应指定该代码在给定文件中的放置位置。

例如，如果某行代码应位于特定函数内，则代码示例应演示该空间顺序，而不是在没有上下文的情况下显示该代码行。

请参阅指定代码位置的示例。

示例

syslog::fx_log_info!("{}, log!", greeting());

syslog::fx_log_info!("{}, log!", greeting());

  use fuchsia_syslog as syslog;

  fn main() {
      syslog::init().expect("should not fail");
      syslog::fx_log_info!("{}, log!", greeting());
      println!("{}, world!", greeting());
  }
  …

确认成功

作为用户，如果您不熟悉新流程，即使已完成记录的所有步骤，也很难知道自己是否已正确完成该流程。

在方法指南中添加一个部分，指定开发者如何确认他们是否已成功实现手术。如果可能，此部分应包含预期结果的终端输出。这样做有助于提高用户信心。

请参阅以下代码示例，了解如何确认操作是否成功。

示例