Google is committed to advancing racial equity for Black communities. See how.

Code sample style guidelines

This document describes best practices for incorporating code samples in documentation.

Code samples are a way to disambiguate documentation because code samples can provide a clear model for how developers can create and format their code.

If you are including a code sample in your documentation, refer to the following to ensure code sample clarity:

For information on general documentation standards for fuchsia.dev, see Documentation standards.

Write comprehensively

When documenting a scenario that you are deeply familiar with, you might overlook information that is necessary to the process 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 requisite information only needed to be completed once and as a result, you can't recall those steps at the time of writing documentation.

When incorporating code samples, think about the process from end-to-end and include prerequisite steps to completing the process.

Specify what success looks like

As a user, when you’re unfamiliar with a new process, it’s difficult to know if you are completing a given procedure correctly.

To increase user confidence, specify what the user's code should look like and how the user can confirm that they have completed tge process successfully.

Review 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.

Apply code sample guidelines

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:

"services": [ "fuchsia.example.Foo" ],

To add a service, you must edit your component manifest (.cmx). For example, adding the fuchsia.sys.Launcher service to your component manifest gives your component the ability to launch other components.

  "sandbox": {
              "services": [ "fuchsia.sys.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 fx log.
  4. cd ~/fuchsia

    fx log

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

    fx shell run fuchsia-pkg://fuchsia.com/hello_world_rust#meta/hello_world_rust.cmx

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