Skip to content

Style Guide

Jump to bottom
catherine-martlin edited this page Jan 23, 2019 · 3 revisions

Python Code Style Guide for jwql

This document serves as a style guide for all jwql software development. Any requested contribution to the jwql code repository should be checked against this guide, and any violation of the guide should be fixed before the code is committed to the master branch. Please refer to the accompanying example.py script for a example code that abides by this style guide.

Prerequisite Reading

It is assumed that the reader of this style guide has read and is familiar with the following:

Workflow

All software development for the jwql project should follow a continuous integration workflow, described in the git & GitHub workflow for contributing. Before committing any code changes, use flake8 to check the code against PEP8 standards. Also check that your code is conforming to this style guide.

Version Numbers and Tags

Any changes pushed to the master branch should be tagged with a version number. The version number convention is x.y.z, where

x = The main version number.  Increase when making incompatible API changes.
y = The feature number.  Increase when change contains a new feature with or without bug fixes.
z = The hotfix number. Increase when change only contains bug fixes.

Security

The following items should never be committed in the jwql source code or GitHub issues/pull requests:

  • Account credentials of any kind (e.g. database usernames and passwords)
  • Internal directory structures or filepaths
  • Machine names
  • Proprietary data

If jwql code needs to be aware of this information, it should be stored in a configuration file that is not part of the jwql repository.

Additionally, developers of this project should be mindful of application security risks, and should adhere to the OWASP Top 10 as best possible.

jwql-Specific Code Standards

jwql code shall adhere to the PEP8 conventions save for the following exceptions:

  • Lines of code need not to be restricted to 79 characters. However, it is encouraged to break up obnoxiously long lines into several lines if it benefits the overall readability of the code

Additionally, the code shall adhere to the following special guidelines:

  • Function and class definitions should be placed in alphabetical order in the module
  • It is encouraged to annotate variables and functions using the typing module (see PEP 483, PEP 484, and PEP 526). In addition, it is recommended that code be type-checked using mypy before a pull request is submitted.

jwql-Specific Documentation Standards

jwql code shall adhere to the PEP257 and numpydoc conventions. The following are further recommendations:

  • Each module should have at minimum a description, Authors and Use section.
  • Each function/method should have at minimum a description, Parameters (if necessary), and Returns (if necessary) sections

jwql-Specific Logging Standards

jwql logging shall adhere to conventions we plan to update shortly. The following points will be further recommendations and also updated shortly.

Tools and Library Recommendations

  • argparse for parsing command line arguments
  • bokeh for interactive plotting
Clone this wiki locally