Read Me

Create a folder for every weekly project. Use the number of the assignment as its name. For example, the first weekly project must exist in a folder called 1.

They do say that the best way to keep a secret on a computer is to place it in a file named README.

Add a README.txt file to the weekly project directory. The first line of the file states the purpose of the project. Otherwise the file consists of up to three additional segments.

This first segment of the README.txt file must always explain the purpose of each file in the directory (excluding itself). Dedicate a line to each file; if the purpose of a file uses more than a sentence of 66 chars, consider breaking up the file.

If the project requests the delivery of code, the second segment of README.txt tells the reader how to use the program. Usually this means how to launch the application. If necessary, it also comes with a paragraph that explains how to interact with the running program. Good software development also requires instructions on how to run internal unit tests so that a maintainer can start by formulating a failed unit test for a bug fix.

Ideally code should reflect the underlying design decisions so that readers do not have to rely on unchecked comments. Some consider the design of sufficiently expressive programming languages the holy grail of our research area.

The third and final part is a road map to the program. It spells out how a reader should go about reading the code. As you know from your first four courses in the College, code must explain itself so do not write an essay here. Just say where to start reading code, what to read then, and so on. If a piece of code demands additional explanation, add a comment to the code; keep in mind that comments are not checked.