Code: Coding style guide

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 docstrings below.

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

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.

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 example below and in napoleon/sphinx documentation example

  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 -- current volume
          channel -- current channel
          current_state -- one of current_state_options
          current_state_options -- ['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) -- turns on a 10 kHz lowpass filter before 
                         data sent to the output (default True)
              volume (float, optional) -- volume for sound output (default 0.5)
  
          Returns:
              None
          
          Exceptions:
              NotImplementedError -- the given channel is not available
              CannotHearAnythingException -- selected volume is too loud
          """