1 @node Coding Standards, Project Documentation, Multilevel Feedback Scheduling, Top
2 @appendix Coding Standards
4 All of you should have taken a class like CS 107, so we expect you to
5 be familiar with some set of coding standards such as
6 @uref{http://www.stanford.edu/class/cs140/projects/misc/CodingStandards.pdf,
7 , CS 107 Coding Standards}. Even if you've taken 107, we recommend
8 reviewing that document. We expect code at the "Peer-Review Quality"
9 level as described there.
11 Our standards for coding are mostly important in grading. More
12 information on our grading methodology can be found on the Course Info
13 page and the Grading page. We also want to stress that aside from the
14 fact that we are explicitly basing part of your grade on these things,
15 good coding practices will improve the quality of your code. This
16 makes it easier for your partners to interact with it, and ultimately,
17 will improve your chances of having a good working program. That said
18 once, the rest of this document will discuss only the ways in which
19 our coding standards will affect our grading.
23 * Conditional Compilation::
25 * Unsafe String Functions::
31 Style, for the purposes of our grading, refers to how readable your
32 code is. At minimum, this means that your code is well formatted, your
33 variable names are descriptive and your functions are decomposed and
34 well commented. Any other factors which make it hard (or easy) for us
35 to read or use your code will be reflected in your style grade.
37 The existing Pintos code is written in the GNU style and largely
38 follows the @uref{http://www.gnu.org/prep/standards_toc.html, , GNU
39 Coding Standards}. We encourage you to follow the applicable parts of
40 them too, especially chapter 5, ``Making the Best Use of C.'' Using a
41 different style won't cause actual problems, but it's ugly to see
42 gratuitous differences in style from one function to another. If your
43 code is too ugly, it will cost you points.
45 Pintos comments sometimes refer to external standards or
46 specifications by writing a name inside square brackets, like this:
47 @code{[IA32-v3]}. These names refer to the reference names used in
48 this documentation (@pxref{References}).
50 If you remove existing Pintos code, please delete it from your source
51 file entirely. Don't just put it into a comment or a conditional
52 compilation directive, because that makes the resulting code hard to
53 read. We're only going to do a compile in the directory for the current
54 project, so you don't need to make sure that the previous projects also
57 @node Conditional Compilation
58 @section Conditional Compilation
60 Given the scope and complexity of your assignments this quarter, you
61 may find it convenient while coding and debugging (and we will find it
62 convenient while grading) to be able to independently turn different
63 parts of the assignments on and off. To do this, choose a macro name
64 and use it in conditional
65 compilation directives, e.g.:
69 @dots{}your code@dots{}
73 In general, the code that you turn in must not depend on conditional
74 compilation directives. Project code should be written so that all of
75 the subproblems for the project function together, and it should
76 compile properly without the need for any new macros to be defined.
77 There are a few exceptions:
81 Problem 1-2, @func{thread_join}. Some other code expects
82 @code{THREAD_JOIN_IMPLEMENTED} to be defined once you've implemented
86 Problem 1-4, the advanced scheduler. We must be able to turn this on
87 and off with a compile-time directive. You must use the macro name we
88 specify for that part. @xref{Problem 1-4 Advanced Scheduler}, for
92 Problem 3-2, paging to and from disk. Your page replacement policy must
93 default to LRU-like replacement, but we must be able to choose a random
94 replacement policy with a compile-time directive. You must use the
95 macro name we specify for that part. @xref{Problem 3-2 Paging To and
96 From Disk}, for details.
99 Code written for extra credit may be included conditionally. If the
100 extra credit code changes the normally expected functionality of the
101 code, then it @emph{must} be included conditionally, and it must not
102 be enabled by default.
105 You can use @file{constants.h} in @file{pintos/src} to define macros
106 for conditional compilation. We will replace the @file{constants.h}
107 that you supply with one of our own when we test your code, so do not
108 define anything important in it.
113 The Pintos source code uses a few features of the ``C99'' standard
114 library that were not in the original 1989 standard for C. Because
115 they are so new, most classes do not cover these features, so this
116 section will describe them. The new features used in Pintos are
117 mostly in new headers:
121 Defines macros @code{bool}, a 1-bit type that takes on only the values
122 0 and 1, @code{true}, which expands to 1, and @code{false}, which
126 On systems that support them, this header defines types
127 @code{int@var{n}_t} and @code{uint@var{n}_t} for @var{n} = 8, 16, 32,
128 64, and possibly others. These are 2's complement signed and unsigned
129 types, respectively, with the given number of bits.
131 On systems where it is possible, this header also defines types
132 @code{intptr_t} and @code{uintptr_t}, which are integer types big
133 enough to hold a pointer.
135 On all systems, this header defines types @code{intmax_t} and
136 @code{uintmax_t}, which are the system's signed and unsigned integer
137 types with the widest ranges.
139 For every signed integer type @code{@var{type}_t} it defines, as well
140 as for @code{ptrdiff_t} defined in @file{<stddef.h>}, this header also
141 defines macros @code{@var{type}_MAX} and @code{@var{type}_MIN} that
142 give the type's range. Similarly, for every unsigned integer type
143 @code{@var{type}_t} defined here, as well as for @code{size_t} defined
144 in @file{<stddef.h>}, this header defines a @code{@var{type}_MAX}
145 macro giving its maximum value.
148 @file{<stdint.h>} is useful on its own, but it provides no way to pass
149 the types it defines to @func{printf} and related functions. This
150 header provides macros to help with that. For every
151 @code{int@var{n}_t} defined by @file{<stdint.h>}, it provides macros
152 @code{PRId@var{n}} and @code{PRIi@var{n}} for formatting values of
153 that type with @code{"%d"} and @code{"%i"}. Similarly, for every
154 @code{uint@var{n}_t}, it provides @code{PRIo@var{n}},
155 @code{PRIu@var{n}}, @code{PRIu@var{x}}, and @code{PRIu@var{X}}.
157 You use these something like this, taking advantage of the fact that
158 the C compiler concatenates adjacent string literals:
160 #include <inttypes.h>
162 int32_t value = @dots{};
163 printf ("value=%08"PRId32"\n", value);
166 The @samp{%} is not supplied by the @code{PRI} macros. As shown
167 above, you supply it yourself and follow it by any flags, field
171 The @func{printf} function has some new type modifiers for printing
176 For @code{intmax_t} (e.g.@: @samp{%jd}) or @code{uintmax_t} (e.g.@:
180 For @code{size_t} (e.g.@: @samp{%zu}).
183 For @code{ptrdiff_t} (e.g.@: @samp{%td}).
186 Pintos @func{printf} also implements a nonstandard @samp{'} flag that
187 group large numbers with commas to make them easier to read.
190 @node Unsafe String Functions
191 @section Unsafe String Functions
193 A few of the string functions declared in the standard
194 @file{<string.h>} and @file{<stdio.h>} headers are notoriously unsafe.
195 The worst offenders are intentionally not included in the Pintos C
200 When used carelessly this function can overflow the buffer reserved
201 for its output string. Use @func{strlcpy} instead. Refer to
202 comments in its source code in @code{lib/string.c} for documentation.
205 This function can leave its destination buffer without a null string
206 terminator and it has performance problems besides. Again, use
210 Same issue as @func{strcpy}. Use @func{strlcat} instead.
211 Again, refer to comments in its source code in @code{lib/string.c} for
215 The meaning of its buffer size argument often leads to problems.
216 Again, use @func{strlcat}.
219 Uses global data, so it is unsafe in threaded programs such as
220 kernels. Use @func{strtok_r} instead, and see its source code in
221 @code{lib/string.c} for documentation and an example.
224 Same issue as @func{strcpy}. Use @func{snprintf} instead. Refer
225 to comments in @code{lib/stdio.h} for documentation.
228 Same issue as @func{strcpy}. Use @func{vsnprintf} instead.
231 If you try to use any of these functions, you should get a hint from
232 the error message, which will refer to an identifier like
233 @code{dont_use_sprintf_use_snprintf}.