Grading

The following rubric is used to evaluate every project in CS151.

Code	4
Comments	3
Results	5
Write Up	4
Extensions	4
Completed	10

Total	30

The sections below extend the ideas of what is expected in the projects.

Code

Code should be well-formatted and easy to read; use white space (blank lines) and comments to separate blocks of code. Variables and functions should have descriptive, intention-revealing names. The code should use control structures appropriately and functions should demonstrate proper code reuse and abstraction.

All code and auxiliary files required to run the project should be submitted to Moodle as an archive/zip. To archive a project (e.g. project01):

Navigate to your CS151 directory in Finder.
Right click on the project01 directory.
Select "Compress project01" from the menu. This will create a file named project01.zip.
Go to the CS151 website.
Click on the link for the project assignment.
Click on the "Browse..." button at the bottom of the page.
Select the zip file you created in step 3.
Click the "Upload this file" button.

You must keep an electronic copy of your work in case we accidentally lose the copy you submit to Moodle.

Comments

Proper commenting is very important, and is a good habit to form immediately. There are many reasons to do this.

Writing a comment lets you reflect on what code does, which can help you better organize your code.
Comments help anyone reading the code understand how the program is logically structured. This could be you a day later or a year later.
Comments help demonstrate you understand a concept. This is why comments are a component of grading in all CS courses.
Most potential employers would hire someone who can communicate ideas clearly rather than someone who can crank out a bunch of unmaintainable code.

In Python, a single line comment starts with a number symbol, #. A multiple line comment begins and ends with a triple quote, ''', appearing on a separate line. The Python interpreter ignores all text appearing in a comment. For example:

# this is a single line comment

'''
This comment
spans multiple
lines.
'''

There are three important types of comments:

File-level comments should appear at the top of each file and include your name, the creation date, and a short description of the file contents. Any files that we partially created for you should include our name and your name. Use the following format:
```
# Your Name
# CS151, Project 1
# 2/1/2012
# A brief description of the contents.
```

Function-level comments are multiple line comments that start on the first line of a function definition. That is, they should be indented within a function. Each function-level comment should follow this format:

def function(param1, param2):
    '''
    One complete sentence describing the function.
    
    Additional details about the function (if necessary).
    
    Parameters:
    param1 -- the meaning of param1 within this function
    param2 -- the meaning of param2 within this function
    
    Returns:
    a description of any values returned by the function (if any)
    '''

Line-level comments are single line comments that explain what a short block of code following the comment does. These are not required for every line of code. However, they are useful to break up logical blocks of a function.

Try to figure out what the following block of code does and what purpose it serves.

tempfile = "__tmpbill.ppm"

def randomFile(ext):
    files = glob.glob("*." + ext)
    global tempfile
    if tempfile in files:
        files.remove(tempfile)
    return random.choice(files)

Compare this to the example below.

# Brian Eastwood
# 1/1/2012
# Functions for creating a billboard, a sign that displays an image.

# a temporary file name used for resizing images
tempfile = "__tmpbill.ppm"

def randomFile(ext):
    '''
    Selects a file at random with a given extension.
    
    Parameters:
    ext -- the file extension, e.g. ppm
    
    Returns:
    a file name as a string
    '''
    
    # find all files that match the extension
    files = glob.glob("*." + ext)
    
    # exclude the temporary file
    global tempfile
    if tempfile in files:
        files.remove(tempfile)
    
    # return a random selection
    return random.choice(files)

Results

Each project in CS151 involves creating images. The results of each program should be incorporated into the Wiki write up page with a useful description. The sophistication of coding is often directly reflected in the images produced, so the sophistication of the results will form a component of the final grade for the project.

Write Up

Write ups in this course are structured after technical academic writing. The target audience for the write ups are students who are not familiar with the course.

The course projects are divided into groups of three related projects. Each week, you will focus on writing a component of the write up while revising components you have worked on in previous weeks. The focus sections for each project will be outlined in the Write Up section of the project description.

Introduction: The introduction is a brief summary of the overall goal of the related group of projects. This should provide a context for the projects and identify the key goals.
Methods: The methods section describes the solution to the tasks and includes proper use of terminology that has been introduced in the course. This section should include any answers to questions posed in the project descriptions.
Results: The results section presents the output of your programs along with useful descriptions. Include in this section a description of any extensions completed, along with images demonstrating those extensions.
Conclusion: The conclusion should include a brief description of what you learned.

Write ups should be completed on the Colby Wiki within your personal space. Be sure to give your write up a descriptive name and to label your page with the label that appears in the project description.

Extensions

Each assignment will have a set of suggested extensions. The required tasks constitute about 85% of the assignment, and if you do only the required tasks and do them well you will earn a B. To earn a higher grade, you need to undertake one or more extensions.

Each project description will include several suggested extensions. You are free to select from these or move in a completely different direction; work on what interests you most. The difficulty and quality of the extensions will be incorporated into the final grade for the project. One complex extension, done well, or 2-3 simple extensions are typical.