1 @node Project Documentation, Debugging Tools, Coding Standards, Top
2 @appendix Project Documentation
4 When you submit your projects, you will be expected to also turn in
5 three files documenting them: @file{README}, @file{DESIGNDOC} and
6 @file{TESTCASE}. These guidelines explain what we want to see in
9 Your submission should have exactly one of each file, in the
10 appropriate directory (e.g.@: for Assignment 1, place the files in the
11 @file{threads} directory). These files must be written in plain text
12 format (not Microsoft Word, not PDF). We recommend a text width of 65
13 characters per line, with a hard limit of 80. If you use tab characters
14 in your document files, be sure that your text editor's tab width is set
24 @section @file{README}
26 This is the easiest of the bunch. It's the document we'll read while
27 trying to get your assignment to run. First, place all of your names
28 and Leland IDs (usernames) at the top. Next, you should also explain
29 any quirks with your program, such as known show-stopper bugs, weird
30 dependencies, and so on.
32 If you added extra credit features to your project, explain them
33 concisely in the @file{README}. Otherwise, we're likely to miss them.
36 @section @file{DESIGNDOC}
38 This file is our primary tool for assessing your design. Therefore,
39 you should be certain to explain your design in some decent amount of
40 detail. As a broad rule of thumb, we should be able to explain what
41 basic data structures and algorithms you used to solve the problem
42 after reading the @file{DESIGNDOC}, but without looking at the code.
44 The easiest way to present your @file{DESIGNDOC} is to break it down
45 by parts of the project (e.g.@: for project 1, you can break the
46 @file{DESIGNDOC} into four parts). For each part, you should describe
47 the functionality that needs to be added, the data structures and
48 algorithms used to solve that problem from a high level, and the
49 motivations for each decision/change you make to the code. Your
50 @file{DESIGNDOC} needs to explain and justify your design. That is,
51 we should be able to understand what you did, and why you chose to do
52 it that way. The ``why'' should be in concrete terms of greater speed,
53 better space efficiency, cleaner code, or some other real measure of
56 Things you @emph{don't} need: an explanation of the pre-existing
57 Pintos code, an explanation of the project spec, justification for the
58 project (e.g.@: we don't need you to explain to us why filesystems are
59 important to an operating system), a play-by-play of every change you
60 made to the system, any other pontificating. (You may laugh at some
61 of the things listed above, but we've gotten all of them in the past.)
62 The @file{DESIGNDOC} needs to discuss design decisions and trade-offs
63 and the rationales behind them. Any other things can be left out, to
64 save your time and ours.
66 Finally, please keep your @file{DESIGNDOC} as short as you can,
67 without sacrificing key design decisions. You should be brief, yet
68 complete. We don't want to read novels.
71 @section @file{TESTCASE}
73 The @file{TESTCASE} file should contain all the information about how
74 you tested your programs. At minimum, this file should contain the
75 output from all the tests that we've provided, with any explanations
76 needed to reproduce the output (arguments to the program, turning
77 features on the program on or off, and so on).
79 Additionally, you should detail all tests you write yourself. You are
80 expected to write tests for features which our tests don't cover, and
81 to write some additional stress tests, since our tests will not
82 necessarily be too strenuous. If you feel that such tests are not
83 required, you should explain why you feel so. For each test that you
84 write, explain how we can use them, and show some sample output from a
87 Here are some pointers for writing @file{TESTCASE} files:
91 Show us that you tested each part of your assignment.
94 Clearly state in your @file{TESTCASE} file what each test is supposed
95 to test. You should be testing not only the common case, but testing
96 corner cases. Specify what criteria or issue is being tested.
99 Make your tests as succinct as possible.
102 Your test cases should be placed in a subdirectory called
103 @file{testcases} within the project directory. So for project 1, they
104 should be in @file{pintos/src/threads/testcases}.
107 Think about what may actually crash your code.
110 Think about what the compiler might do to your code. Suppose you write
111 the following to test your virtual memory implementation's ability to
120 @noindent The compiler is quite likely to notice that the value that you
121 write to the array is never used again and thereby decide not to write
122 it at all. The result is that your test does not test anything at all.
125 Your @file{TESTCASE} file is also where you can show us the
126 improvements that your code makes to the performance of the system.
127 You should be able to show us ``before'' and ``after'' performance
128 data, and explain how the data shows the improvement. For example,
129 for Problem 1-3, you should show us in the @file{TESTCASE} printouts
130 from a workload for the non-Solaris scheduler and the Solaris
131 scheduler and explain why the Solaris scheduler is better.
133 Finally, we cannot stress enough the importance of being brief and
136 Keep in mind that the quality of your testing is worth 10% of your
137 project grade. The bulk of this will be determined from the
138 @file{TESTCASE} file.