oslo-incubator/HACKING.rst

Oslo Style Commandments

• Step 1: Read the OpenStack Style Commandments http://docs.openstack.org/developer/hacking/
• Step 2: Read on

Oslo Specific Commandments

• None So Far

General

• When defining global constants, define them before functions and classes

• Use 'raise' instead of 'raise e' to preserve original traceback or exception being reraised:

  except Exception as e:
      ...
      raise e  # BAD
  
  except Exception:
      ...
      raise  # OKAY

TODO vs FIXME

• TODO(name): implies that something should be done (cleanup, refactoring, etc), but is expected to be functional.
• FIXME(name): implies that the method/function/etc shouldn't be used until that code is resolved and bug fixed.

Text encoding

• All text within python code should be of type 'unicode'.

  WRONG:

  >>> s = 'foo' >>> s 'foo' >>> type(s) <type 'str'>

  RIGHT:

  >>> u = u'foo' >>> u u'foo' >>> type(u) <type 'unicode'>

• Transitions between internal unicode and external strings should always be immediately and explicitly encoded or decoded.

• All external text that is not explicitly encoded (database storage, commandline arguments, etc.) should be presumed to be encoded as utf-8.

  WRONG:

  mystring = infile.readline() myreturnstring = do_some_magic_with(mystring) outfile.write(myreturnstring)

  RIGHT:

  mystring = infile.readline() mytext = s.decode('utf-8') returntext = do_some_magic_with(mytext) returnstring = returntext.encode('utf-8') outfile.write(returnstring)