Comp202: Principles of Object-Oriented Programming II
Fall 2006 -- README Guidelines   

When we grade your project, the first thing we will look for is the README file in the root of the assignment directory.   The assignment directory is the root directory of the directory tree that you zip up to hand in.   NEVER just leave a bunch of source code files there, and leave your grader to guess what you supposed to do.

The README file should serve as a clear description of what you have done (and what you have not done if you don't finish some part), and aroadmap of what other files and directories inside your assignment directory are about.

You should also give a *high* level documentation of your work.  (Don't expect your comment in source code can do that. It only serves as low level documentation of your code, but not overall understanding of your project.

This should include introduction of the problems you solve, your solutions, including algorithm, data structure(class, method, relations between classes). However, for this part, you should avoid simply listing together some code excerpts, and tell what each fields and methods are.  Instead you should give general description so others can understand your work without digging into much details of lengthy code. Some
pseudo-code may be necessary, but use it sparingly.

We expect your README file to be a format of mini technical report, at least have the following sections:

  1. roadmap of your directory -- Description of all the files and dirs, stay inside your directory,
    clean out those temporary files before you turn in. Document how to compile and run your code, whether your code is fully functional, or some parts still missing.
  2. introduction section of the problem and your solution
  3. high level description of algorithm, data structure(class, method, relations between classes) and avoid too low level distraction.
  4. testing and verification -- Describe your testing effort, the test classes, methods and test cases.

Good documentation is integral component of good software development.  So start sharpen your skills of that from now!


Last Revised Thursday, 03-Jun-2010 09:52:23 CDT

©2006 Stephen Wong and Dung Nguyen