Homework Assignment 4; CS 450

The goal is to have each person review two other programs and to have their program reviewed by two peers. You are not required to indicate your name in the review.

Part 0: Quick Check For Problems ASAP (before break is best)

You should have two other students homework 3 directories copied into your hw4 directory. Spend 2 minutes double-checking that you can read all the files and compile the program. If you have any trouble, let me know ASAP.

Part 1: Write up a usability review of each person's program

You have access to the other student's code, but first try to extract as much information as possible without looking at their code.

1. Critique MANPAGE

Does the MANPAGE give a clear description of how to run their program?

Do they give examples of use? Do you know how to designate the input file? Do you know where the output will be placed? Do you know how to use the various options (total words, distinct words, word frequency list, etc?

Do you have criticisms of their use interface? Would it be easy to automate use of this program through a script?

Do they give examples of valid/invalid words?

Do they point out any limitations or known bugs? (Keep this in mind in case you run into some later!)

Is there anything else you would have liked to see in their MANPAGE file?

2. Critique their README.

Are you able compile the program according to their instructions? Do you have to do more than type make?

Do they clearly define a word? Do you think their definition is a good/useful one?

Do they give you a clear sense of the purpose of each source code file?

Do they clearly indicate the basic data structures used? Do you agree with their choice?

3. Compile and run the program.

Can you compile and run the program according to their directions?

What happens if you make a mistake with the inputs you choose? Do they point out the error in a reasonable way?

What happens if you specify a file that does not exist? What happens if you run the executable with no arguements?

Correctness

Do you see any errors in the output of their program? We will be doing a more exhaustive testing phase later, but for right now run their program on some of the files you have used to test your own program. Do you get the same answers? If not, try to explain the discrepancies. Do they appear to be following the definition they gave?

If you wanted to automate a comparision between the output of your program and the other student's program, what would you need to do?

Performance analysis

Consider what types of files might expose poor performance in someone's program. For example, the following dictionary file is a good test because it is a large file in which each word appears only once.

For each file in the testFiles directory, run their program asking it to report the most common word, report the running time and the most common word.

FOOD FOR THOUGHT: What other things would you want to report in order to make these performance numbers really useful?

Part 2: Code Review

You know exactly what their code is supposed to do since you just wrote another program to do the same thing! Still, how easy is it for you to find the same major elements in their code?

1. Structure/Overview

How easy is to get a quick overview of their code? If there are multiple code files, does the README describe the relationship between them?

When you open a file, are there comments at the top to aid the reader - who wrote this code, what is the purpose of this file?

Is it easy to find the major code path? What is it?

If you didn't already know what this code was doing would it be obvious from the accompanying documentation and by reading the code itself?

2. Modularity

Are routines/modules well designed to hide information and to encapsulate the handling of data?

3. Data Structures Chosen

Is it easy to determine the major data structures they are using in the code? Does it match what the README says?

4. Readability

Overall how readable is their code? Are variable names well chosen? Is formatting consistent and helpful? Is their commenting style helpful in understanding their code?

5. Defensive Programming

Do they program defensively? Do they consistently check the return codes of functions like opening files and allocating memory? Do they use assertions? Do they use them properly?

4. Limitations

In the README, do they mention any limitations on their program (e.g. limits on types of files, size of files, length of words, etc.)? Even if they don't mention it, can you discover any unreasonable limits they have placed in their code?

5. Advice

Do you have any advice for them about how they could program more efficiently? Do you see any ways they could simplify the program?

Did you garner any advice from reading their code about how you could do things more efficiently?

6. Maintainability

How would you feel about continuing on with their code for the next assignment? Is their code structured well to accomodate change?

7. Other comments

Overall, how similar was their code to yours?

Do you have any other comments?

Part 3: Submit your assignment.

You must check the following files into /afs/clarkson.edu/class/cs450/students/YOUR_USERNAME/hw4 : usabilityReview.STUDENT and codeReview.STUDENT (where STUDENT is replaced with the email address of the student whose code you reviews, e.g. if you had reviewed my code, codeReview.jnm).

As you review someone elses work, you may very well realize changes you would like to make to your own. If so, don't submit the changes with this assignment; simply make the changes to a personal copy of your own program and related documenation, and then save them until you turn in the next round of the homework.