Make more useful.
[pintos-anon] / doc / doc.texi
1 @node Project Documentation, Debugging Tools, Coding Standards, Top
2 @appendix Project Documentation
3
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
7 those files.
8
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.
14
15 @menu
16 * README::                      
17 * DESIGNDOC     ::              
18 * TESTCASE      ::              
19 @end menu
20
21 @node README
22 @section @file{README}
23
24 This is the easiest of the bunch.  It's the document we'll read while
25 trying to get your assignment to run.  First, place all of your names
26 and Leland IDs (usernames) at the top.  Next, you should also explain
27 any quirks with your program, such as known show-stopper bugs, weird
28 dependencies, and so on.
29
30 If you added extra credit features to your project, explain them
31 concisely in the @file{README}.  Otherwise, we're likely to miss them.
32
33 @node DESIGNDOC         
34 @section @file{DESIGNDOC}
35
36 This file is our primary tool for assessing your design.  Therefore,
37 you should be certain to explain your design in some decent amount of
38 detail.  As a broad rule of thumb, we should be able to explain what
39 basic data structures and algorithms you used to solve the problem
40 after reading the @file{DESIGNDOC}, but without looking at the code.
41
42 The easiest way to present your @file{DESIGNDOC} is to break it down
43 by parts of the project (e.g.@: for project 1, you can break the
44 @file{DESIGNDOC} into four parts).  For each part, you should describe
45 the functionality that needs to be added, the data structures and
46 algorithms used to solve that problem from a high level, and the
47 motivations for each decision/change you make to the code.  Your
48 @file{DESIGNDOC} needs to explain and justify your design.  That is,
49 we should be able to understand what you did, and why you chose to do
50 it that way.  The ``why'' should be in concrete terms of greater speed,
51 better space efficiency, cleaner code, or some other real measure of
52 goodness.
53
54 Things you @emph{don't} need: an explanation of the pre-existing
55 Pintos code, an explanation of the project spec, justification for the
56 project (e.g.@: we don't need you to explain to us why filesystems are
57 important to an operating system), a play-by-play of every change you
58 made to the system, any other pontificating.  (You may laugh at some
59 of the things listed above, but we've gotten all of them in the past.)
60 The @file{DESIGNDOC} needs to discuss design decisions and trade-offs
61 and the rationales behind them.  Any other things can be left out, to
62 save your time and ours.
63
64 Finally, please keep your @file{DESIGNDOC} as short as you can,
65 without sacrificing key design decisions.  You should be brief, yet
66 complete.  We don't want to read novels.
67
68 @node TESTCASE  
69 @section @file{TESTCASE}
70
71 The @file{TESTCASE} file should contain all the information about how
72 you tested your programs.  At minimum, this file should contain the
73 output from all the tests that we've provided, with any explanations
74 needed to reproduce the output (arguments to the program, turning
75 features on the program on or off, and so on).
76
77 Additionally, you should detail all tests you write yourself.  You are
78 expected to write tests for features which our tests don't cover, and
79 to write some additional stress tests, since our tests will not
80 necessarily be too strenuous.  If you feel that such tests are not
81 required, you should explain why you feel so.  For each test that you
82 write, explain how we can use them, and show some sample output from a
83 run.
84
85 Specifically, here are some pointers for writing @file{TESTCASE} files
86 which will make them more succinct and us more likely to understand the
87 tests you write:
88
89 @itemize @bullet
90 @item
91 Show us that you tested each part of your assignment.
92
93 @item
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.  For
97 example, in testing @code{thread_join()} you would have specified that
98 you test @code{thread_join()} when it is called multiple times on the
99 same child thread.
100
101 @item
102 Make your tests as succinct as possible.  Most students in the past
103 have done a great job with the testing of @code{thread_join()},
104 creating very succinct short tests.  We like that.
105
106 @item
107 Your test cases should be placed in a subdirectory called
108 @file{testcases} within the project directory.  So for project 1, they
109 should be in @file{pintos/src/threads/testcases}.
110
111 @item
112 Think about what may actually crash your code.
113 @end itemize
114
115 Your @file{TESTCASE} file is also where you can show us the
116 improvements that your code makes to the performance of the system.
117 You should be able to show us ``before'' and ``after'' performance
118 data, and explain how the data shows the improvement.  For example,
119 for Problem 1-4, you should show us in the @file{TESTCASE} printouts
120 from a workload for the non-Solaris scheduler and the Solaris
121 scheduler and explain why the Solaris scheduler is better.
122
123 Finally, we cannot stress enough the importance of being brief and
124 complete.
125
126 Keep in mind that the quality of your testing is worth 10% of your
127 project grade.  The bulk of this will be determined from the
128 @file{TESTCASE} file.