I am currently learning to program in Python and I think that since my programming experience might not be too extensive, it is a good opportunity to start building good coding habits. Along with the Coding Style Guidelines from the Coursera course Principles of Computing by Rice University, I will be using other sources, mainly the official Python documentation (PEP8). I will try to update this post as often as possible and if you find any errors or if you have any suggestions, please do send me a message or post a comment. I will really appreciate it.
It is important to always document code. Not only to allow someone else to understand your design and implementation decisions, but to leave “breadcrumbs” to follow your way along your own code. After working in a project or a piece of code for some time, you might forget why you chose to use a module or why you defined a certain function the way you did. Documentation is much for your own benefit as well as for others.
However, documenting code is more than just tossing comments here and there, or leaving funny remarks. Well organized, structured comments can become useful pieces of information. Python provides a mechanism to extract these pieces of information interactively from a command prompt with the use of the help(…) or the module.__doc__ method. But documentation needs to follow a set of rules in order to be extracted by this Python functionality. The convention for docstrings is described in the PEP257 (Python Enhancement Proposal) of the Python documentation.
All docstrings are enclosed within triple single quotes (”’), with the first line of a multiline comment ending with a period (.), and should always be placed as follows:
- At the top of each module (file) to describe what it does
- Below a Class definition to describe what it does and what it returns
- Below a Method definition within a Class to describe what it does
- Below a Function definition to describe what it does and to explain the Function’s arguments
You can find more on docstrings in this post.
Comments are placed within Python by starting a line with a hash (#) and they are intended to explain how a piece of code does something complex. Do not over use comments or comment the obvious, rather briefly explain why you made that design choice. Comments should not be multi-line strings either. They are not docstrings and should not be used instead of docstrings, or docstrings in place of comments.
This is a good multi-line comment:
# This is a comment # That spans several lines
This is not a good multi-line comment:
''' This is a docstring format. Used in place of a comment. Using this as a comment is not standard style convention. '''
Global variables should be used in limited amounts inside any code. They should only be limited to very few instances, probably where you need to store the environment state of your program. An exception to this should be CONSTANTS. Since Python does not define CONSTANTS as such, they are a type of global variable. Always use capital letters to write CONSTANTS, so you know that they should never be modified.
Python uses blank spaces for indentation instead of tabs. Each indented block should be offset from its parent block by four (4) blank spaces. Some IDEs will automatically indent with four spaces after a piece of code which requires a new block is defined. Other IDEs or environments will also automatically replace tabs with blank spaces. To keep with good coding style practices, always indent in Python using blank spaces.
Names for variables, functions, methods, and classes should be at least 3 characters long. The names assigned to each one can be constructed as follows:
- Variables, Functions, and Methods should start with a lowercase letter. By convention, all of these Python names should also avoid using any capital letters. To separate words you can use underscore: this_is_a_valid_variable_name.
- Classes should always start with an uppercase letter and should not have any space or underscore: ThisIsAValidClassName.
- If you want to declare any name as private, you can use an underscore as a first character. After this, you have to follow the above conventions. Remember that private names should not be access outside of their context: _this_variable_is_private,
You should avoid repeating a name in an outer scope, since this will make the outer-scope name not accessible. The same happens with Python reserved names. If you declare an existing Python function/method name within a certain scope (Function, Method, Class), that Python reserved function/method will not be accessible within that scope.
Arguments and Local Variables
There is no limit on the number of arguments passed to a function or the number of local variables declared. However, to make the code easier to read and maintain, it is recommended to use a smaller number of arguments. Some tools, like Pylint, will actually detect this as an error. If you have too many arguments passed to a declaration, then you better split this into simpler components.
Local variables never used should not be declared. Pylint also detects this as an error. In certain cases, like loops, it is useful to declare a dummy variable to iterate over. In this case it is recommended to prefix the variable with the word dummy_:
for number in range(10): do something # Would be better declared as: for dummy_number in range(10): do something