The ReadMe File

Many people these days fail to understand the purpose of a readme file (you're probably thinking, those daft TAs, just giving us extra busy work as if we don't already have enough....) Here, then, is a brief outline of a good readme file for any assignment:

Assignment name

===============

Assignment author

Assignment date

Author's email address

Table of Contents:

I Outline of algorithm

II Files and contents

III User guide

(how to compile and run the code)

IV Sample output

V Discussion:

What does/doesn't work and why, any extra functionality, extraneous problems (e.g. it rained on my laptop so I had to recode everything in 5 hours the day it was due)

I Outline of algorithm

What approach did you take? What are the objects/data structures you used? How does your algorithm meet the project specifications? A little diagram showing how data moves would be nice.

II Files and contents

What files are you turning in? What classes or functions are in which files?

III User guide

How does one compile your program? Is there a makefile? Are there any special libraries (eg maths) that must be included for compilation)? How does one use your program? What should the input look like? What kinds of error messages are given if the user does something wrong? What errors are not caught?

IV Sample output

Self-explanatory, I hope.

V Discussion

Again, pretty self-explanatory. If you don't tell us about things you did differently, we might not notice you did them at all, so tell.

A Bad Example -- Never Do This.

Here is a bad readme file. The stuff in []'s is what the TA might imagine the student is thinking:

"For this program, I created 3 classes [but I'm not going to tell you what they are, or I don't know what they are. Also I don't know what files I put them in. It's guess-the-class time.]. The user will be asked for 3 things [but I don't know what they are, or I'm not going to tell you what they are. Also, I'm not sure how the user should input those things, or in what order, or how I'm going to use them.]. Then I'll print the output [but I don't know what it looks like, and I'm certainly not going to tell you or give you any examples in case you can't figure out on your own what the input is and so can't produce your own output....].

"I like this project [but I can't tell you what files I put my work in, or how to compile them.]."

By not turning in a proper readme file, you indicate that you want to annoy the person marking your project as much as possible, or at the very least that you didn't properly design and test your solution.

By turning in a proper readme file, you not only demonstrate the competence of your solution, you also clarify what exactly you have done (especially helpful if you did something "extra".) If any files get lost, we will know from your readme file. Writing a good readme file also gives you the opportunity to check and make sure you have done everything; to "organize" yourself. Finally, it means that 7 months from now you will be able to go back and figure out what exactly you did and how you might be able to reuse some of your code.

Please turn in a good readme file.