Parsons Coding Conventions

The following is a list of best practices to consider when writing code for the Parsons project:

• Each tool connector should be its own unique class (e.g. ActionKit, VAN) in its own Python package. Use existing connectors as examples when deciding how to layout your code.

• Methods should be named using a verb_noun structure, such as get_activist() or update_event().

• Methods should reflect the vocabulary utilized by the original tool where possible to maintain transparency. For example, Google Cloud Storage refers to file like objects as blobs. The methods are called get_blob() rather than get_file().

• Methods that can work with arbitrarily large data (e.g. database or API queries) should use of Parson Tables to hold the data instead of standard Python collections (e.g. lists, dicts).

• You should avoid abbreviations for method names and variable names where possible.

• Inline comments explaining complex codes and methods are appreciated.

• Classes and methods should always have documentation strings (docstrings) and tests.

• Capitalize the word Parsons for consistency where possible, especially in documentation.

If you are building a new connector or extending an existing connector, there are more best practices in the Adding a New Connector documentation.