CONTRIBUTING.md

Development Environment

We recommend a virtual python environment for development, a more detailed description of the setup process can be found in the docs.

Testing

SaQC comes with an extensive test suite based on pytest. In order to run all tests execute python -m pytest ., for faster iteration a test run with python -m pytest --ignore test/lib test is usually enough.

Coding conventions

Naming

Code

We implement the following naming conventions:

• Classes: CamelCase
• Functions: camelCase
• Variables/Arguments: snake_case

Argument names in public functions signatures

First, in contrast to variable names in code, it is not necessary to have talking function argument names. A user is always expected to have had acknowledged the documentation. Using and parameterizing a function, just by guessing the meaning of the argument names, without having read the documentation, will almost never work. That is the reason, why we dont have the obligation to make names (very) talkative.

Second, from the nature of a function to deliver a simple way of using complex code, it follows, that simple and short names are to prefer. This means, the encoding of irrelevant informations in names should be omitted.

For example, take a function of three arguments, that fits a polynomial to some data. Lets say we have:

• the data input,
• a threshold, that defines a cutoff point for a calculation on a polynomial and
• a third argument.

One could name the corresponding arguments: data, poly_cutoff_threshold, .... However, much better names would be: data, thresh, ..., because a caller that is aware of a functions documentation doesnt need the extra information, encoded in the name. If the third argument is also some kind of threshold, one can use data, cutoff, thresh, because the thresh- information of the cutoff parameter is not crucial, and the caller knows that this is a threshold from having studied the docstring, anyways.

Third, underscores give a nice implicit feedback, on whether one is doing wrong or getting over complex in the naming behavior. To have no underscore, is just fine. Having one underscore, is ok, if the encoded information appended through the underscore is really necessary (see above). If one uses two or more underscores, one should think of a better naming or omit some information. Sure, although it is seldom, it might sometimes be necessary to use two underscores, but still the usage of two underscores is considered bad style. Using three or more underscores is not allowed unless having issued a exhaustive and accepted (by at least one core developer per underscore) reasoning.

In short, the naming should give a very, very rough idea of the purpose of the argument, but not explain the usage or the purpose. It is not a shame to name a parameter just n or alpha etc., if, for example, the algorithm (from the paper etc.) names it alike.

Test Functions

• testnames: [testmodule_]flagTestName

Formatting