1.2 Documentation

Documentation / Comments (PART 1)

Comments are notes that describe what is happening in the code. The comments are not for Python, they are for a human to read.

In Python, anything to the right of a '#' is a comment, and Python ignores it. Look at the following two lines of code, and predict what will happen:

print('Hi')

# print('Hi')

The '#' turned the second example into a comment. It is not a statement any longer. It can't be executed.

Why would we use this?

If you are working with a formula like area = hw, you would want to describe it in a comment:

area = h * w # area is equal to height times width

Now, anyone who reads your code, understands exactly what is happening in your formula.

Poor comments:

area = h * w # formula

area = h * w # area = hw

Neither one of these comments help the reader understand what is happening in your formula. They just restate the formula.

You will provide internal documentation (comments) for all your work. Check out the programming rubric, a large portion of your mark comes from documentation.

The secret is to comment as you code. Going back to comment a small program is annoying. Going back to comment a large project is daunting.

Comment as you code.

Along with in-line comments, you must also provide a header to every file. Headers look like this:

#  Author:

# Date:

# File Name:

# Description:

The first three areas of the header are easy to understand. The fourth section is YOUR UNDERSTANDING of my question. Do not re-copy my question and paste it. I know what my question is, I want to know what you've understood my question to be.

Comments are part of a larger idea called documentation.

Documentation isn't just for the next programmer who reads your code, but it's also for the user. There are 3 levels of documentation:

In-line documentation - comments

On-line documentation - help while the program is running. On-line doesn't mean the internet. Think 'Help' Option in the menu.

External documentation - help while the program is not running.

You will be responsible for internal documentation for now. I'll let you know when the other levels come into play.

Basic Points:

1. Remember that a large portion of your mark comes from pseudo-code and comments.
2. When in doubt, comment.
3. Comments should be as clear and elegant as your solution, not an after thought.
4. Most importantly: Comment as you code. Going back to comment after is annoying on small programs, and daunting on larger programs

Choosing what to comment:

1. The top level comment block A.K.A the header comment
   1. Program Name
   2. Author
   3. Date
   4. Clear Description
2. All variables and objects. Remember the clearer the actual names, the easier it is to comment
3. Your algorithm / formula
4. Decision structures (Selection and Repetition)