Basic style tips for writing scripts

To make clean, readable code, it is encouraged to follow these basic tips about how the code should be written and organized. The main rule enforced by Python is the indentation required, which is intended to make the code easier to read and write. The major Python style suggestions and implementations are collectively contained in the Python Enhancement Proposal 8, also known as PEP8. We have included our own recommendations as well, based on lots of experience.

Indentation

Python code has strict indentation rules that are enforced by all IDEs. These rules relate to functions and loops especially.

As a standard, four spaces are used after a function is declared, a loop is created, or a conditional is used. This is just a standard, as it could be only one space or however many spaces you want, but that indentation level becomes important when scripts get big. It helps to have four spaces for all indented lines so that they can be more easily read.

Do not mix tabs and spaces when indenting, as this will make it impossible to execute scripts in some IDEs.

Using print statements

The built-in function called print() is used to send messages from the script to the command window while the script is running. Pass any valid data to the print() statement and use it to track progress or to debug if there are issues:

>>> print("blueberry")
blueberry
>>> x = 0
>>> print(x)
0

Debugging using print statements is very common, and I encourage it as you learn to code. Well-placed print statements will help you understand how the code execution is progressing, and will help you to find the source of bugs by telling you which part of the script has executed and which part has not. It is not a requirement to use print statements, but they really are a programmer’s friend.

Structuring a script

We suggest the following guidelines for good script structure:

• Add a comment at the top with script details: This is an optional but recommended way to start your scripts: write a comment at the top with your name, the date, and a quick explanation about what the script is supposed to do. This is especially nice when other people have to read your code.

  Add lots of other comments throughout the script as well, to make sure you know what is happening throughout the script.

• Follow with import statements: It is encouraged, but not required, to put the import statements at or near the top of the script. Imports must happen before the module objects are called in the script, but the import statements can be placed anywhere. It is best to put them at the top so that people reading the script can understand what is being imported.
• Define global variables: After the import statements, define the necessary variables that will be used in this script. Sometimes it is necessary to define variables later in the script, but it is best to put major variables near the top.
• Define functions: By placing function definitions below the global variables, it is easy to read and understand what the functions do when reading them. It is sometimes hard to find a function that is called in another part of the script if the function is not in a known location in the script.
• Write the executable parts of the script: After importing modules and defining functions, the next part of the script is where the action takes place. The for loops are run, the functions are called, and the script is then done.

  Make sure to add lots of comments to help yourself understand what is happening throughout the script, and print statements as well to help while the script is running.

• if __name__ == '__main__': Often at the end of scripts you will see this line. What it means is that the indented code below this line will be run if the script is executed directly, but if the code in the script is imported by another script, the code blocks will not execute until called in the second script.