代码示例样式指南

本文档介绍了如何将代码示例整合到文档中， 和具体的样式指南。其中包括：

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

有关常规文档标准（包括文件类型、位置和常规设置）的信息， 请参阅 Fuchsia 文档标准。 如需有关用词、样式和结构的具体指导，请参阅 Fuchsia 文档样式指南。

代码示例最佳做法

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

例如，在开始使用代码示例之前，请考虑所有必需的前提信息。确保您没有忽略使用示例所需但不再出现在日常工作流中的必要信息。

这可能是因为您已多次执行这些步骤，因此这些步骤不再显得对流程至关重要。这可能还因为这些前提条件信息只需完成一次，因此您在编写文档时无法回想这些步骤。如果可能，请尝试 从一开始就开始测试您的样本，并验证您是否具备所有前提条件 记录信息。

同样，请务必通知用户何时成功完成 正确执行这一给定过程。要提高用户对样本的置信度，请确保 应指定用户代码的外观以及用户如何确认 已成功运行您的示例。

代码示例核对清单

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

• 在文档中添加“前提条件”部分，作为文档中的第一个部分。 在用户开始流程之前，在文档中收集前提条件信息，可防止用户不必要地被阻止或感到沮丧。
  • 前提条件信息可以包括以下任一内容：
    • 修改环境变量。
    • 在开始该过程之前运行必要的脚本。
    • 获取设备访问权限。
    • 包括 BUILD 依赖项。
    • 导入库。
• 指向现有文档的链接（如果适用）。 例如，您要记录的流程的前提条件 可能是已刷写的 Fuchsia 目标设备。 请不要重复说明如何刷写设备，而是链接到 fuchsia.dev 上现有的“刷写”主题，例如构建和刷写 Fuchsia。
• 如果您属于以下情况，请避免使用 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());
  }
  …

确认成功

作为用户，当您不熟悉新流程时 即使您已经 已完成记录的所有步骤。

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

请参阅以下示例，了解如何在代码示例中确认成功。

示例