oslo-incubator/HACKING.rst
Joe Gordon fd9aee535e Update URL for global HACKING document
Related to I579e7c889f3addc2cd40bce0c584bbc70bf435e2

Change-Id: I1db5934ec6fa0052fdbfa9c60fee16495237969e
2013-11-11 10:36:08 -08:00

1.6 KiB

Oslo Style Commandments

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)