Friday, April 20, 2012

Python coding conventions

It is often a confusion in my team regarding what practice to follow while coding in python.
I have research it (mainly from PEP-08) and am sharing my findings.
Code Style
Zen of Python (PEP-20)
Type import this on python shell to see the zen of python.

The Zen of Python, by Tim Peters
Beautiful is better than ugly.
Explicit is better than implicit.
Simple is better than complex.
Complex is better than complicated.
Flat is better than nested.
Sparse is better than dense.
Readability counts.
Special cases aren't special enough to break the rules.
Although practicality beats purity.
Errors should never pass silently.
Unless explicitly silenced.
In the face of ambiguity, refuse the temptation to guess.
There should be one-- and preferably only one --obvious way to do it.
Although that way may not be obvious at first unless you're Dutch.
Now is better than never.
Although never is often better than *right* now.
If the implementation is hard to explain, it's a bad idea.
If the implementation is easy to explain, it may be a good idea.
Namespaces are one honking great idea -- let's do more of those!


Naming Conventions
As the naming conventions of python are otherwise loosely defined, some rules were created to be followed by all standardized modules.
In this, the python community is undecided. Generally, the java convention is followed, but with an underscore instead of capital letter between letters in a word, but capital case as in C# is also observed.

Underscore usage:
This is not a syntactical requirement, but a convention.
 weak "internal use" indicator. Eg; from M import * does not import objects in M which start with an _
 used by convention to avoid conflicts with Python keyword. Eg; class_ m

Abbreviations should be capitalized like URLBroadcastListener

Code lay-out
Use of 4 spaces per indentation level, avoid tabs and do not mix tabs with spaces.
Do not exceed 80 character lines.
Avoid compound statements (single line having more than one line of code separated by a semicolon ; )
Blank lines can be used to perform the following:
To separate logical spaces(only if necessary) within the methods.
To separate different methods within a class.
Class definitions and functions may have 2 blank lines in between.

Each should be on separate lines, but could be supplied on the same line if presnet in same namespace.
Order of imports:
  Standard imports
  Related third party imports
  Local application/library imports
Use absolute imports from within the namespace instead of relative values.
Specify clearly, if using a module containing a class as: from namespace.classname import classname to reduce ambiguity

Whitespace formatting is best left to our own descretion, and should make the code readable.
Reiterating this often forgotten best practice- Never mix tabs with spaces.
Avoid WhiteSpaces at:
Just after start of parenthesis or a method call. eg: def meth ( arg): #Both the spaces around (
Just before a comma, semicolon or a colon. eg: def meth(arg , arg2) :
Just before indexes. eg: collect ['paper']
More than a single whitespace around operators. eg: pi  =  3.14159
No whitespaces should be used around keyword arguments or in assigning default parameter values
Compound statements on the same line (separated with a ; or : ) are discouraged as they affect readability.

Comments & Documentation strings
Here too, common programming rules apply: Comments should only be used if code is not easily decipherable; and should be updated with code changes.
Comments should be complete line in itself with longer ones finishing with a period (.)
Block comments start before any block of code with a single # and a space.
Inline comments should be rarely used, if that particular line performs something critical for the developer's attention.
Documentation strings (aka documentation comments in some languages) should be written for all public classes, methods, functions and modules.
These should preferably be in multiple line.

Docstring Conventions
These conventions are optional, as they pertain to the documentation portion of python. Still, these can be quite handy if you would be releasing the api documentation of your application later as api generators like Docutils require that you conform to a specified convention.
Docstring is a string literal occuring at the first statement of a method or class.
It is created using three " literals and can be single or multi line.

It is worth noting that the zen of python must take precedence over yours or mine preferences. This is necessary to allow programmers from diverse backgrounds to communicate effectively in code (ours was a mix of java, C# and visual basic programmers and we were using a wrapper of a C++ library, leading to major headaches and refactoring towards code maintenance).

No comments: