Python Coding style guidelines

Python

Maybe, it’s an aspect not worth on computer science, but when a software grows, using a coding style guidelines can avoid you big problems when, in the future, you need to review your own code, or even review code written by others,

Python has been really concious of this aspect, so here is the recommendations:

Docstrings

Documentation strings (“docstrings”) are an integral part of the Python language, and they are always in triple quotes “”” docstring “””. They need to be in the following places:

  • At the top of each file describing the purpose of the module.
  • Below each class definition describing the purpose of the class.
  • Below each function definition describing the purpose of the function.

You need to describe what is does, not how it is done! In the case of functions, it’s very useful to comment what the function does, the arguments needed and the output.

Docstrings are important because is exists several good tools to automatically give you documentation for modules, classes, functions, and method, and it’s an aspect every developer should take care of!

Comments

Comments should describe how a section of code is accomplishing something. You should not comment obvious code. Instead, you should document complex design decisions about why a particular coding choice was made, etc.

Comments start with #, and it’s not the same that comments starting with “”” text “””, because these are not comment, but a string in the middle of your code!

Global Variables

Global variables should never be used in this class. Avoiding their use is good programming practice in any language, although some times are inevitable.

The only exception is constants. In Python, constants are declared as variabled, and are named always capitalized.

Indentation

As Python requires indentation to be consistent, it is important not to mix tabs and spaces. You should never use tabs for indentation. Instead, all indentation levels should be 4 spaces.

Variable names

All variable, function, class, and method names must be at least 3 characters. The first character of a name should follow these conventions:

  • Variable names should always start with a lower case letter. (Except for variables that represent constants, which should use all upper case letters.)
  • Function and method names should always start with a lower case letter.
  • Class names should always start with an upper case letter.

It is also a good practice not to include an upper case letter on a variable, instead, use _.

Class fields

Class and instance fields should never be accessed directly from outside the class. You should therefore always start your field names with an underscore. Even if you don’t, you still should not access them from outside of the class.

Scope

Also, the variables’s scope is another important topic. You should avoid duplicate variable names, and in the case it occurs, the closer is used. So, watch out with the definition of variable names!

Arguments and variables

There is no maximum, but it is important to use as less variables or arguments as possible, for avoiding too complex code.

And last ….

There is a fundamental rule on Python:

Design your functions to do one thing and do it well

so, read carefully this entrance and start practicing, because in the future it can save you a lot of time!