Fork PyRPL on GitHub

5.4. Coding style guidelines

5.4.1. General guidelines

We follow the recommendations from PEP8.

Concerning line length, we have tried to stick to the 79 characters allowed by PEP8 so far. However, since this definitely restricts the readability of our code, we will accept 119 characters in the future (but please keep this at least consistent within the entire function or class). See the section on Docstrings below.

Other interesting policies that we should gladly accept are given here. - Django style guide

5.4.2. Naming conventions

  • Capital letters for each new word in class names, such as class TestMyClass(object):.
  • Lowercase letters with underscores for functions, such as def test_my_class():.
  • Any methods or attributes of objects that might be visible in the user API (i.e. which are not themselves hidden) should serve an actual purpose, i.e. pyrpl.lockbox.lock(), and so on.
  • Any methods or attributes that are only used internally should be hidden from the API by preceeding the name with an underscore, such as pyrpl.rp.scope._hidden_attribute or pyrpl.spectrum_analyzer._setup_something_for_the_measurement().
  • Anything that is expected to return immediately and does not require an argument should be a property, asynchronous function calls or one that must pass arguments are implemented as methods.

5.4.3. Docstrings

Since we use sphinx for automatic documentation generation, we must ensure consistency of docstrings among all files in order to generate a nice documentation:

  • follow PEP257 and docstrings in google-style — please read these documents now!!!

  • keep the maximum width of docstring lines to 79 characters (i.e. 79 characters counted from the first non-whitespace character of the line)

  • stay consistent with existing docstrings

  • you should make use of the markup syntax allowed by sphinx

  • we use docstrings in google-style, together with the sphinx-extension napoleon to format them as nice as the harder-to-read (in the source code) sphinx docstrings

  • the guidelines are summarized in the napoleon/sphinx documentation example or in the example below:

    class SoundScope(Module):
        An oscilloscope that converts measured data into sound.
        The oscilloscope works by acquiring the data from the redpitaya scope
        implemented in pyrpl/fpga/rtl/red_pitaya_scope_block.v, subsequent
        conversion through the commonly-known `Kolmogorov-Audio algorithm
        <>`_ and finally outputting sound
        with the python package "PyAudio".
            play_sound: start sending data to speaker
            stop: stop the sound output
            volume (float): Current volume
            channel (int): Current channel
            current_state (str): One of ``current_state_options``
            current_state_options (list of str): ['playing', 'stopped']
        def play_sound(self, channel, lowpass=True, volume=0.5):
            Start sending data of a scope channel to a speaker.
                channel (int): Scope channel to use as data input
                lowpass (bool, optional): Turns on a 10 kHz lowpass
                    filter before data sent to the output. Defaults to True.
                volume (float, optional): volume for sound output.
                    Defaults to 0.5.
                bool: True for success, False otherwise.
                NotImplementedError: The given channel is not available.
                CannotHearAnythingException: Selected volume is too loud.