Version 1 (modified by fhuici, 8 years ago)

--

Provisional HEN Python coding style

This is a *provisional* attempt to lay down some rules that we can adhere to and moan about. The style is only intended to apply to new code, not code that we import. Hopefully, the style is equidistant from our default coding styles that all are equally peturbed.

- DOCTRINE

Ignore any section of this document when doing so would enhance readability. Feel free to edit someone else's code into agreement with these principles, or into agreement with your own variant of these principles. Expect that your code may be likewise edited.

- FILE PROLOGUES

Files should have a prologue containing the copyright, and a description of what the file does.

- INDENTATION

Use 4 spaces per indent level. This is what emacs' Python mode does.

- COMMENTS

Use # for comments.

Avoid obvious comments inside routines. Any comments inside routines should be short. Prefer single blank lines for separating sections of code.

- API DOCUMENTATION (pydoc)

All major routines should have a comment briefly describing what they do. We use pydoc comments to generate API overviews and programming documentation.

- TERMINAL WIDTH

Assume the terminal is 80 characters wide. Sure there'll be odd times when wraps cannot be avoided, but gratuitous wrapping will give you a "wide boy" reputation.

Use the '\' at the end of a line to break long lines, but don't worry about breaking long parameter lists in function definitions.

- CAPITALIZATION

class Wrench:

def init(self, weight=None):

self.weight = weight

def getWeight(self):

return self.weigth

- UNDERSCORING

Member variables as well as private member functions should begin with two underscores. Regular variables and function names should separate words with capital letters.

- NAMES FOR MODIFIERS AND ACCESSORS.

Often, a private member variable will have associated functions that get and/or set its value. If the variable is named "xxx", name the getter function "getXxx()" and the setter function "setXxx()".

- ABBREVIATIONS

Should be avoided, especially in method names.

- INCLUDE FILES

Include files should be sorted into domain, each domain separated by a blank line:

kernel includes sys includes net includes default include path includes local includes

Don't sweat it too hard, however.

- PYTHON SHORTCUTS

Use the 'in' keyword when traversing lists, rather than a combination of the range and len functions.

- SPACES AND PARENTHESES

Binary operators should have spaces around them to ease decipherment. Parentheses have to used when precedence dictates and can be used to reduce confusion, particularly with long expressions. Do not put spaces around parentheses.

Keywords should likewise have spaces around them. For example, if (x)', not if(x)'; and return x', not return(x)'.

Do not leave spaces between a parameter's name and its default value. For example def setWeight(weight=3):' rather than def setWeight(weight = 3)'. Do leave spaces between parameters however.

Leave spaces on both sides of a '+' sign when concatenating strings.

- VARIABLE DECLARATIONS

Place variable declarations at the beginning of the relevant scope. This includes placing declarations in the middle of functions, close to their first uses, when appropriate. Declare iteration variables inside the `for' statement when possible; this is most of the time. Declare a test variable inside the `if' test when possible; this happens comparatively rarely. Prefer multiple declarations when defining several variables that require initializers.