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(), pyrpl.rp.iq.bandwidth 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:

• 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
<http://www.wikipedia.org/Kolmogorov>_ and finally outputting sound
with the python package "PyAudio".

Methods:
play_sound: start sending data to speaker
stop: stop the sound output

Attributes:
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.

Args:
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.

Returns:
bool: True for success, False otherwise.

Raises:
NotImplementedError: The given channel is not available.
CannotHearAnythingException: Selected volume is too loud.
"""