Code sample style guidelines

This document describes how to incorporate code samples in documentation, and specific style guidelines for code samples. This includes:

• Code sample best practices
• Code sample checklist
• Code sample style guide

For information on general documentation standards, including file types, locations, and general tone, see the Fuchsia documentation standards. For specific guidance on word choice, style, and structure, see the Fuchsia documentation style guide.

Code sample best practices

When creating a code sample for a part of Fuchsia that you are deeply familiar with, consider how a new user would read the sample and try to anticipate their needs. Think about the process from end-to-end and include prerequisite steps to completing the process and specify what success looks like.

For example, consider all of the prerequisite information needed before starting to use the code sample. Make sure you're not overlooking information that is necessary to use the sample but no longer present in your day-to-day workflow.

This might be because you have done these steps so many times that these steps no longer stand out as necessary to the procedure. It also might be because this prerequisite information only needed to be completed once and as a result, you can't recall those steps at the time of writing documentation. If possible, try running your sample from the very beginning, and verify that you have all of the prerequisite information documented.

Likewise, it's important to let the user know when they have successfully completed a given procedure correctly. To increase user confidence in your sample, make sure you specify what the user's code should look like and how the user can confirm that they have completed running your sample successfully.

Code sample checklist

If you are including a code sample in your documentation, review the following list before submitting your contribution, to ensure code sample clarity:

• Include a "Prerequisites" section, as the first section within your documentation. Having prerequisite information gathered within documentation, before the user starts the process, prevents the user from becoming unnecessarily blocked or frustrated.
  • Prerequisite information can include any of the following:
    • Editing environment variables.
    • Running necessary scripts before starting the procedure.
    • Obtaining device access.
    • Including BUILD dependencies.
    • Importing libraries.
• Link to existing documentation where applicable. For example, a prerequisite for the process you are documenting might be a flashed Fuchsia target device. Rather than restating how to flash one’s device, link to an existing “Flash” topic that already exists on fuchsia.dev, such as Build and flash Fuchsia.
• Avoid using foo, bar, or other vague placeholder names if you are including placeholders in your code sample. Instead, use a name that expresses what that placeholder's function is within the code. For more information, see Avoid vague placeholders.
• Anchor developers within the process by stating the obvious. Anticipate that someone might run code samples without thoroughly reading your documentation. As a result, make sure your codes samples are spatially aware. For more information, see Specify placement.
• End sections with a code sample summary that details what the finished code is supposed to look like at a given point in a procedure. For more information, see Specify placement and Confirm success.
• Describe the steps needed to test the process and show what successful terminal output looks like.

Code sample style guide

The following are actionable best practices for creating easily understandable code samples in documentation.

Avoid vague placeholders

Code sample placeholder names and values should represent their purposes within the code, avoiding abstract placeholders like foo and bar.

• Use a placeholder name that expresses what the placeholder’s function is within that code. Doing so gives developers a real-world example that they can refer back to at a later point.

• Code samples should be able to be copied into the terminal and run successfully without extensive alteration by the user.

Refer to the following example of avoiding vague placeholders.

Example

protocol: "fuchsia.example.Foo"

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

Specify placement

Code samples should be specify where that code should be located within a given file.

For example, if a line of code should be located within a specific function, then the code sample should demonstrate that spatial order, rather than show that line of code without context.

Refer to the example of specifying code location.

Example

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());
  }
  …

Confirm success

As a user, when you’re unfamiliar with a new process, it’s difficult to know if you have completed that process correctly, even if you've completed all of the documented steps.

Include a section in your how-to guide that specifies how developers can confirm that they have successfully implemented a procedure. If possible, this section should include the terminal output of the expected result. Doing so can help increase user confidence.

Refer to the following example of confirming success in code samples.

Example