Skip to content

code_formatting.rst

Latest commit

 

History

History
102 lines (75 loc) · 2.47 KB

code_formatting.rst

File metadata and controls

102 lines (75 loc) · 2.47 KB
Raw

Code Formatting

Flake8 is run on the codebase according to parameters in the .flake8 file following PEP8 conventions where possible.

Naming Conventions

  • Classes are named in CamelCase, e.g. HttpCommon, Orchestrator, EdgeConnect
  • Functions are variables are named in snake_case, e.g. get_appliances()
  • Private functions begin with _ e.g. _get() or _req_post()

Docstrings and comments

  • Docstrings follow Sphinx/reStructured Text Formatting
    • Short initial description
    • Reference to where to find this function in Swagger UI
    • Longer description, notes, examples if applicable
    • parameter and return descriptions and types
  • All functions have docstrings outlining parameters and returns
  • Code in a function begins the line immediately following the docstring

Example:

"""<Short description here>

.. list-table::
    :header-rows: 1

    * - Swagger Section
      - Method
      - Endpoint
    * - <swagger section> -> e.g. login
      - <method> -> e.g. GET
      - <endpoint> -> e.g. /logout

<longer description>

.. note::

    an optional note

.. warning::

    an optional warning

:param <param name>: <param description>
:type <param name>: <param type>
:return: <return description>
:rtype: <return type>
"""
<code begins here>

Maximum Line Length

  • All comments and docstrings have a maximum line length of 72 characters
  • All functional code has a maximum line length of 79 characters
  • In the rare case when a string or docstring can't be wrapped over multiple lines (e.g. specifying a long API endpoint in docstring) use # noqa: at the end of the docstring with E501 for extending past 79 and W505 for extending past 72, or just W505 if past 72 but within 79.

Example:

"""docstring

.. list-table::
    :header-rows: 1

    * - Swagger Section
      - Method
      - Endpoint
    * - login
      - GET
      - /long_endpoint/path/{that_cannot}/be/wrapped/over_multiple_lines
...
""" # noqa: W505

Type Hinting (PEP585)

  • All parameters for functions have type hinting following PEP585 (Python 3.9+) formatting with generic types.

    def my_func(my_var: str) -> dict:
...
# or
def my_func(my_var: list[int]) -> list:
...