Code sample style guidelines

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

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 paved Fuchsia target device. Rather than restating how to pave one’s device, link to an existing “Pave” topic that already exists on fuchsia.dev, such as Build and pave quickstart.
  • 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

To add a service, include the following:

protocol: "fuchsia.example.Foo"

To add a service, you must edit your component manifest (.cml). For example, adding the fuchsia.process.Launcher service to your component manifest gives your component the ability to launch processes.

  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

Add the following:

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

Include your log message within your source file, which in this case is, main.rs:

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

At this point, main.rs should look like this:

  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

By adding the above code, you have enabled logging in Fuchsia.

At this point you have enabled logging in Fuchsia. To confirm that you have logging enabled in your component, complete the following steps:

  1. Ensure that fx serve is running in a shell tab. If it is not, open a shell tab and run fx serve.
  2. cd ~/fuchsia

    fx serve

  3. In a new shell tab, navigate to your fuchsia directory and run ffx log.
  4. cd ~/fuchsia

    ffx log

  5. In a new shell tab, navigate to your fuchsia directory and run the hello_world_rust component:
  6. cd ~/fuchsia

    ffx component run /core/ffx-laboratory:hello-world fuchsia-pkg://fuchsia.com/hello-world-rust#meta/hello-world-rust.cm

  7. Navigate to the shell tab where you ran ffx log.
  8. You should be able to see your logging text, which in this example is Hello log!.