conventions

Conventions

Code

This repository aims to support python 3 version that are actively supported (currently >= 3.6). Python coding conventions should be followed:

• Adhere to PEP 8
• Use pylint to ensure as clean and well-formatted code as possible
• When relevant, adhere to clean coding practices

Documentation (lifted from PISA)

Documentation comes in two forms: docstrings and standalone files (either markdown .md files or reStructuredText .rst files). Docstrings are the most important for physics and framework developers to consider, and can (and should) be quite far-ranging in their scope. Standalone files are reserved for guides (install guide, developer’s guide, user’s guide, quick-start, etc.) and one README.md file within each directory to document the directory’s raison d’être, or what is common to all of the things contained in the directory.

All documentation will be (TBD) run through Sphinx using the Napoleon (to understand Numpy-style docstrings) and Recommonmark (to understand Markdown syntax) extensions, so the final arbiter of whether a docstring is formatted "correctly" is the output generated using these. Refer to those links for how to format docstrings / Markdown to produce a desired result.

Docstrings

Docstrings can document nearly everything within a Python file. The various types of docstrings are:

• module: beneath the authorship, at the top of the .py file
  • Why did you create this file (module)? What purpose does it serve? Are there issues that the user should be aware of? Good and bad situations for using the class(es) and function(s) contained? Anything that doesn’t fit into the more usage-oriented docstrings below should go here.
• function: beneath the function declaration line
  • What the function does, args to the function, notes
• class: beneath the class declaration line
  • Purpose of the class, instantiation args for the class, notes to go into more detail, references, …
• method: beneath the method declaration line
  • Purpose of the method, args to the method, notes
• attribute: beneath the definition of a variable (in any scope in the file)
  • What purpose it serves. Note that if you add an attribute docstring, the attribute is included in the documentation, while if you do not add such a docstring, the attribute does not appear in the documentation.

Examples of the above can be seen and are discussed further in the tutorial for creating a service.

Docstrings should be formatted according to the Google-style convention.

Standalone files

...

Tests

Unit testing is done using pytest. Unit tests should go in dedicated folder in the the top-level directory (gnn_reco/tests/), such that a module gnn_reco/src/gnn_reco/module.py is accompanied by a unit test file gnn_reco/tests/test_module.py. Per clean coding guidelines, the unit test file should contain (ideally) several test functions, each containing (ideally) only one assert-statement.

• Adapted from Tensorflow:
  • Include unit tests when you contribute new features, as they help to a) prove that your code works correctly, and b) guard against future breaking changes to lower the maintenance cost.
  • Bug fixes also generally require unit tests, because the presence of bugs usually indicates insufficient test coverage.
  • Tests should follow the testing best practices guide.