pigweed/docs/style_guide.rst

.. _docs-pw-style:

============
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``

.. grid:: 2

   .. grid-item-card:: :octicon:`diff-added` C++ style
      :link: docs-pw-style-cpp
      :link-type: ref
      :class-item: sales-pitch-cta-primary

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


   .. grid-item-card:: :octicon:`pencil` Commit messages
      :link: docs-pw-style-commit-message
      :link-type: ref
      :class-item: sales-pitch-cta-secondary

      How to format commit messages for Pigweed

.. grid:: 2

   .. grid-item-card:: :octicon:`code-square` Protobuf
      :link: docs-pw-style-protobuf
      :link-type: ref
      :class-item: sales-pitch-cta-secondary

      How to structure reference documentation for C++ code

   .. grid-item-card:: :octicon:`terminal` CLI style
      :link: docs-pw-style-cli
      :link-type: ref
      :class-item: sales-pitch-cta-secondary

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

--------------------------
Documentation style guides
--------------------------
See the :ref:`documentation contributors homepage <docs-contrib-docs>`.

.. todo-check: disable

.. _docs-pw-todo-style:

----------
TODO style
----------
Pigweed expects TODO annotations to adhere to the following style:

.. todo-check: disable

.. code-block:: py

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

.. todo-check: enable

.. admonition:: Note

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

In Markdown docs like
`Rustdoc <https://doc.rust-lang.org/rustdoc/what-is-rustdoc.html>`_
the following format is preferred:

.. todo-check: disable

.. code-block:: rs

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

.. todo-check: enable

.. admonition:: 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-check: disable

.. code-block:: py

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

.. todo-check: enable

.. todo-check: enable

-----------------
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:

.. code-block:: none

   // 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:

.. code-block:: none

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

---------------
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
<https://docs.bazel.build/versions/main/build-ref.html>`_
(see the `Bazel style guide
<https://docs.bazel.build/versions/main/skylark/build-style.html>`_).

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.

.. code-block:: cpp

   # 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
<https://docs.bazel.build/versions/main/skylark/build-style.html>`_.

------------------
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
:ref:`module-pw_build_android`.

.. _owners-style:

--------------------
Code Owners (OWNERS)
--------------------
If you use Gerrit for source code hosting and have the
`code-owners <https://android-review.googlesource.com/plugins/code-owners/Documentation/backend-find-owners.html>`__
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".

.. toctree::
   :hidden:

   Bazel <style/bazel>
   C++ <style/cpp>
   Commit message <style/commit_message>
   CLI <style/cli>
   Protobuf <style/protobuf>
   Python <style/python>
   reStructuredText <style/rest>
   Doxygen <style/doxygen>
   Writing <style/writing>