Tip

Programs must be written for people to read, and only incidentally for machines to execute. — Abelson & Sussman, Structure and Interpretation of Computer Programs

4. Python Code Style

Text Editor

I recommend these text editors for python development :

  • Sublime text : very beautiful interface, Python syntax highlighting, Python plugins.
  • vim : for all linuxer
  • NotePad++ : I always use this editor although my friends mocking me :(( Having a perfect NppFPT for virtual machine, and mostly it has an option to backup all my source code each time I do Ctrl+S.
  • Pycharm : Full-featured IDE for Python. I tried it once, a very nice interface, autocorrect following PEP8 standart, and efficient but it’s so slow.

4.1. Indentation

Whitespace 1

  • 4 spaces per indentation level.
  • Never mix tabs and spaces.
  • One blank line between functions.
  • Two blank lines between classes.

Whitespace 2

  • Add a space after ”,” in dict, list, tuple, & argument lists, and after ”:” in dicts, but not before.
  • Put spaces around assignments & comparisons (except in argument lists).
  • No spaces just inside parentheses or just before argument lists.

Exemple:

def make_squares(key, value=0):
    """
    Return a dictionary and a list.

    @param
        key : string or numeric
        value : any type, by default is 0
    @return
        a tuple 2 element, the first is dictionnary, other is list

    - Exemple :
        make_squares(4)
        make_squares(4,99)
    """
    d = {key: value}
    l = [key, value]
    return d, l

4.2. Convention in Python for variable and function names

  • Class: ClassName
  • Method name : method_name
  • Function : names should be lowercase, with words separated by underscores as necessary to improve readability , example function_name.
  • Variables : lowercase with words separated by underscores as necessary to improve readability.
  • Private methods and properties start with __double_underscore
  • “Protected” methods and properties start with _single_underscore
  • global_var_name
  • instance_var_name
  • local_var_name
  • function_parameter_name
  • Constant name : GLOBAL_CONSTANT_NAME
  • ExceptionName : ExceptionName

Ignored variable

If you need to assign something but will not need that variable, use the double underscores __ (not a single underscore _ in order to avoid confusion with variable to store the result of the last evaluation) :

filename = 'foobar.txt'
basename, __, ext = filename.rpartition('.')

4.3. Docstrings & Comments

  • Docstrings : Explain how to use code, and are for the users of our code. This is written between 2 triple-quotes. This must always have 3 things :

    • Purpose of the function
    • Description the given parameters (name, type, note), we use @param ; the return values (name, type, note), we use @return.
    • Un example to run this function

A linebreak after a block. Exemple :

def sum3(a,b,c) :
    """
    This function to get the sum of 3 given numbers.

    @param:
        a, b, c : numeric type, raise exception if it lacks one
    @return:
        my_sum : numeric type

    - Example : sum3(3, 4.4, -1)
    """
    return a + b + c

Note

When the function is called, the Docstrings is in method __doc__. For the above example, typing print sum3.__doc__ or help(sum3) in python interactive and it show our docstring.

  • Comments : Explain why, and are for the maintainers of our code. Genarally there are 3 types :

    • Block Comments
    • Inline Comments
    • Commenting Out Code for Testing

4.4. autopep8

The library autopep8 automatically formats Python code to conform to the PEP 8 style guide. So good ! For example, I have a python script named my_script.py was bad written, by using this lib, we are safe !

pip install autopep8
autopep8 --in-place my_script.py

4.5. if __name__ == “__main__”

Sometimes we see this notion in source code, that means if we run directly the script from terminal, these command-lines in if block will be executed .By example we have a script a.py :

if __name__ == "__main__":
    print 'hello'

Then run in cmd:

>>> python a.py
hello

But if we import a into another script python, all commands in if __name__ == "__main__" will be not execute, because in this case, __name__ become ‘a’. Exemple we have the script a.py like as above, then we import a.py into b.py:

import a
if __name__ == "__main__":
    print 'hello b'
    print a.__name__

we run :

>>> python b.py
hello b
a

What’s the use ?

This thing’s used for testing when we write a new module or new sub-script in a grand project. For my above exemple, I can write some testsuite after if __name__ == “__main__”: