Good READMES from Homework 5

To give you an idea of what we're looking for in a README, here are some particularly good README's which were submitted for homework 5. In general, characteristics of a good README included:

• Brief or no discussion of concepts which were stated in lecture (eg, how an AVL tree does its rotations)
• Succinct discussion of important design issues that were faced, the solution that was decided upon, as well as the rationale behind the decision.
• For the Shakespeare/Bacon or extra credit analyses, it was important to state:
  1. the problem/question they were answering,
  2. any relevant data that they collected,
  3. an answer to the stated question, which is justified by the collected data.

README 1

This was a good readme because it very quickly jumped past details (such as how to compile/call the program, or lengthy introductions of known materials, like how an AVL tree does its rotations). Design decisions were discussed in detail (for instance, that ValueType needed to overload operator+), with no fanfare.

The word frequency analysis clearly laid out the process they followed.

The profiling clearly laid out their assumptions and their data. The data were actually presented (ie, they had numbers). Hypotheses were stated, and a conclusion was drawn about each one (ie, confirmed, disproven, or that it generated further questions).

README 2

This readme very clearly laid out design principles, and briefly mentions all major design decisions, as well as their justification for what they decided.

The profiling analysis clearly stated their assumptions/misconceptions instead of merely stating profiling results. What they learned, as well as further areas to investigate, are mentioned. A conclusion is stated.

README 3

Again, design problems/decisions are succinctly presented and a solution with its rationale are discussed. For profiling, an explicit "expectations" and "results" section is presented. Unanswered questions and weaknesses of their analysis are also mentioned.

A weak point of this readme is that the sorting algorithm analysis presents information without discussing their justification or where their data came from; this information sounds like it could have been copied from lecture slides.

README 4

This readme succinctly summarizes their code; however, the strength of this readme lies in the extra credit writeup. The profiling results clearly state their assumptions (including an asymptotic bound). Their gprof results were clearly presented, and their analysis indicates what could cause the results they measured.