Style guides#

Tip

Pigweed runs pw format as part of pw presubmit to perform some code formatting checks. To speed up the review process, consider adding pw presubmit as a git push hook using the following command: pw presubmit --install

C++ style

Our C++ style guide: an extension of the Google C++ style with further restrictions and guidance for embedded

Commit messages

How to format commit messages for Pigweed

Protobuf

How to structure reference documentation for C++ code

CLI style

How to style your CLI program so that it behaves consistently with other Pigweed CLI programs

Documentation style guides#

See the documentation contributors homepage.

TODO style#

Pigweed expects TODO annotations to adhere to the following style:

# TODO: https://pwbug.dev/123456789 - Some explanation of the problem at
# hand, which may span multiple lines if necessary.

Note

Please include the https:// to make it easier for code editors to identify the bugs as URLs.

In Markdown docs like Rustdoc the following format is preferred:

//! TODO: <pwbug.dev/123456789> - Explanation.

Note

For Rustdoc, omit https://. The additional Markdown syntax makes the link explicit, and including https:// makes the preamble disruptively lengthy.

Some older forms are still allowed but discouraged. We allow the following formats, ordered by preference with the preferred patterns at the top:

# TODO: https://pwbug.dev/1234 - Explanation.
# TODO: b/1234 - Explanation.
# TODO: username@ - Explanation.
# TODO: username@example.com - Explanation.
# TODO(b/1234): Explanation.
# TODO(username): Explanation.

Copyright headers#

Every Pigweed file containing source code must include copyright and license information. This includes any JS/CSS files that you might be serving out to browsers.

Apache header source code files that support // comments:

// Copyright 2023 The Pigweed Authors
//
// Licensed under the Apache License, Version 2.0 (the "License"); you may not
// use this file except in compliance with the License. You may obtain a copy of
// the License at
//
//     https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
// License for the specific language governing permissions and limitations under
// the License.

Apache header for source code files that support # comments:

# Copyright 2023 The Pigweed Authors
#
# Licensed under the Apache License, Version 2.0 (the "License"); you may not
# use this file except in compliance with the License. You may obtain a copy of
# the License at
#
#     https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations under
# the License.

Python style#

Pigweed uses the standard Python style: PEP8, which is available on the web at https://www.python.org/dev/peps/pep-0008/. All Pigweed Python code should pass pw format, which invokes black with a couple options.

Python versions#

Pigweed officially supports a few Python versions. Upstream Pigweed code must support those Python versions. The only exception is pw_env_setup, which must also support Python 2 and 3.6.

Build files: GN#

Each Pigweed source module requires a GN build file named BUILD.gn. This encapsulates the build targets and specifies their sources and dependencies. GN build files use a format similar to Bazel’s BUILD files (see the Bazel style guide).

C/C++ build targets include a list of fields. The primary fields are:

<public> – public header files
<sources> – source files and private header files
<public_configs> – public build configuration
<configs> – private build configuration
<public_deps> – public dependencies
<deps> – private dependencies

Assets within each field must be listed in alphabetical order.

# Here is a brief example of a GN build file.

import("$dir_pw_unit_test/test.gni")

config("public_include_path") {
  include_dirs = [ "public" ]
  visibility = [":*"]
}

pw_source_set("pw_sample_module") {
  public = [ "public/pw_sample_module/sample_module.h" ]
  sources = [
    "public/pw_sample_module/internal/secret_header.h",
    "sample_module.cc",
    "used_by_sample_module.cc",
  ]
  public_configs = [ ":public_include_path" ]
  public_deps = [ dir_pw_status ]
  deps = [ dir_pw_varint ]
}

pw_test_group("tests") {
  tests = [ ":sample_module_test" ]
}

pw_test("sample_module_test") {
  sources = [ "sample_module_test.cc" ]
  deps = [ ":sample_module" ]
}

pw_doc_group("docs") {
  sources = [ "docs.rst" ]
}

Build files: Bazel#

Build files for the Bazel build system must be named BUILD.bazel. Bazel can interpret files named just BUILD, but Pigweed uses BUILD.bazel to avoid ambiguity with other build systems or tooling.

Pigweed’s Bazel files follow the Bazel style guide.

Build files: Soong#

Build files (blueprints) for the Soong build system must be named Android.bp. The way Pigweed modules and backends are used is documented in pw_build_android.

Code Owners (OWNERS)#

If you use Gerrit for source code hosting and have the code-owners plug-in enabled Pigweed can help you enforce consistent styling on those files and also detects some errors.

The styling follows these rules.

Content is grouped by type of line (Access grant, include, etc).
Each grouping is sorted alphabetically.
Groups are placed the following order with a blank line separating each grouping.
- “set noparent” line
- “include” lines
- “file:” lines
- user grants (some examples: “*”, “foo@example.com”)
- “per-file:” lines

This plugin will, by default, act upon any file named “OWNERS”.