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
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
<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.
"""