Documenting Scripts

1. Introduction

When writing code it is just as important to probably document the code as to get it working. Imagine if you came into a new position and your first task was to finish a program someone had been working on for months. You open the project and find one huge file with several thousand lines of code. There is no documentation on how to program works or how it is structured. As you look through the code the variables are named with just a letter and a number like “A0” and the functions are named “Sub1” and so on. There are no header blocks to describe what the functions do, no comments to explain the details of the code, and the code is written to be a compressed as possible. This is not an exaggeration. This actually happened to me on a project and we basically had to rewrite the entire program from scratch. It has happened to me over and over again in 30 years of programming. To make matters worse, I have often written code and then left it for over a year only to return and find I could not understand what I had written! In one case I wrote some software for our manufacturing group, returned to the group 10 years later, only to find they were still using the same program which I had named “Scan2ex.exe”. If I had realized the program would be around for 10 years I would have at least found a better name for it.

Below are some guidelines for writing the MINIMUM documentation for your programs, you can always add more. However, always remember that the overriding goal is to make sure that if someone else needs to update your code (which happens far more than anyone realizes), they should be able to work just from your documentation. We refer to documentation rather than just comments because good software should start with “paper” documentation (the standard used to be Microsoft Word but these days it may be in HTML, GoogleDocs, or another online format that everyone on a virtual team can access). The paper documentation should include a definition of what the program needs to do, how the program is designed, and how the program was tested. We'll talk more about this at the end of the book in an introduction to software development process.

First, programs should be broken into appropriate “files”, often referred to as "modules". Each module should contain functions that have related functions such as file I/O or graphics. Class files should contain just one class.

2. File Header

Each file should start with a header that contains the name of the file, its purpose, the author, the date it was last modified, any required copyright information, and information on the source of content. Remember that this is the minimum file header and additional information can be added on how the file is structured, what other files it may required to function, and how to call the functions in the file.

	#################################################################
	# UTMConverter
	#
	# Provides functions to:
	# - Convert between UTM  and Geographic coordinates as well
	# - Find UTM Zones and  "South" value from geographic coordinates
	# - Switch between  UTMZones and EPSG Numbers
	#
	# By: Jim Graham
	# Date: 12/12/2007
	# 
	#################################################################

3. Inline Comments

Where ever something is unclear, and there is a good chance it will be unclear to someone else you should add “inline” comments. These comments appear between lines of code and to the right of code. It is rare that code has too many comments so if you think a section of code may need some comments, add them but remember to add the information you would like to see if you were reading the code for the first time.

Additional Resources

Further Reading: Python Style Guide