file structure

All python files will use lowercase by convention, and snake_case in the event that more than one word is used in the file name as a description of the file contents.

All files and functions that we write should contain a docstring:

“A universal convention supplies all of maintainability, clarity, consistency, and a foundation for good programming habits too. What it doesn’t do is insist that you follow it against your will. That’s Python!”

—Tim Peters on comp.lang.python, 2001-06-16

A docstring is the documentation that accompanies your code. It describes what that code will do- this applies both at the level of a file, and the sub-levels of functions and classes.

For the purposes of this course, we will use the following structure in all assignments and projects:

All files will begin with a commented note on the encoding of the file: although this is not something needed by the latest versions of python, it is a convention that we will use, based on epytext- a docstring similar to JavaDoc.

# -*- coding: utf-8 -*-

"""

@author: your_name

@date: dd-mmm-yyyy

@project: Project name

@description:

Write one or many lines here describing the contents of this file or it's purpose

"""

module (file) docstring

The text above in orange is the module docstring- you may copy and paste this into any files you are using and modify appropriately. When you import a module you have written, and then run the python help() function on that module (file) you will be presented with information on the contents of this file. As an example, you may write a module that contains useful helper functions to use with CLI games or applications.

Let us suppose that this file is called helpers.py and contains four functions. In addition to the module docstring as shown above, all of the docstring information has been completed for the functions also.

Note that these docstrings can also be processed with other software utilities as a way to generate all of the required documentation for a software project.

The result of running help() on the helpers file

If you have a helpers.py file, you can view this information by entering the following into the python interpreter in the Shell:

>>> import helpers

>>> help(helpers)

File structure

Immediately after the docstring, we will use the following clearly defined blocks in our file structure:

# -- imports

# -- globals/constants

# -- functions

# -- classes (if used)

# -- main body

if __name__ == "__main__":

main()

To find more information about each of these areas, check out:

Documentation

Using the above guidelines, your python files, functions and classes can be relied upon to generate good quality docuemntation for any software projects that you undertake.

You should always use a tool such as one of the following:

or use this online PEP8 checker.

You should be able to install any or all of these modules in your Windows or Linux environment (Linux shell shown in example) using the following command:

~username$ pip install pycodestyle

and to use this then to check your code:

~username$ pycodestyle helpers.py # specify what file you wish to check

You can substitute the name pycodestyle with any other module that you wish to use. You should always check the documentation for any modules that you are using. Here is a look at the guidelines for using pycodestyle.

Page updated

Google Sites

Report abuse