%d -> %zu.
[pintos-anon] / doc / standards.texi
1 @node Coding Standards, Project Documentation, Multilevel Feedback Scheduling, Top
2 @appendix Coding Standards
3
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.
10
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.
20
21 @menu
22 * Coding Style::                
23 * Conditional Compilation::     
24 * C99::                         
25 * Unsafe String Functions::     
26 @end menu
27
28 @node Coding Style
29 @section Style
30
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.
36
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.
44
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}).
49
50 @node Conditional Compilation
51 @section Conditional Compilation
52
53 Given the scope and complexity of your assignments this quarter, you
54 may find it convenient while coding and debugging (and we will find it
55 convenient while grading) to be able to independently turn different
56 parts of the assignments on and off.  To do this, choose a macro name
57 and use it in conditional
58 compilation directives, e.g.:
59
60 @example
61 #ifdef @var{NAME}
62 @dots{}your code@dots{}
63 #endif
64 @end example
65
66 In general, the code that you turn in must not depend on conditional
67 compilation directives.  Project code should be written so that all of
68 the subproblems for the project function together, and it should
69 compile properly without the need for any new macros to be defined.
70 There are a few exceptions:
71
72 @itemize @bullet
73 @item
74 Problem 1-2, @func{thread_join}.  Some other code expects
75 @code{THREAD_JOIN_IMPLEMENTED} to be defined once you've implemented
76 this function.
77
78 @item
79 Problem 1-4, the advanced scheduler.  We must be able to turn this on
80 and off with a compile-time directive.  You must use the macro name we
81 specify for that part.  @xref{Problem 1-4 Advanced Scheduler}, for
82 details.
83
84 @item
85 Code written for extra credit may be included conditionally.  If the
86 extra credit code changes the normally expected functionality of the
87 code, then it @emph{must} be included conditionally, and it must not
88 be enabled by default.
89 @end itemize
90
91 You can use @file{constants.h} in @file{pintos/src} to define macros
92 for conditional compilation.  We will replace the @file{constants.h}
93 that you supply with one of our own when we test your code, so do not
94 define anything important in it.
95
96 @node C99
97 @section C99
98
99 The Pintos source code uses a few features of the ``C99'' standard
100 library that were not in the original 1989 standard for C.  Because
101 they are so new, most classes do not cover these features, so this
102 section will describe them.  The new features used in Pintos are
103 mostly in new headers:
104
105 @table @file
106 @item <stdbool.h>
107 Defines macros @code{bool}, a 1-bit type that takes on only the values
108 0 and 1, @code{true}, which expands to 1, and @code{false}, which
109 expands to 0.
110
111 @item <stdint.h>
112 On systems that support them, this header defines types
113 @code{int@var{n}_t} and @code{uint@var{n}_t} for @var{n} = 8, 16, 32,
114 64, and possibly others.  These are 2's complement signed and unsigned
115 types, respectively, with the given number of bits.  
116
117 On systems where it is possible, this header also defines types
118 @code{intptr_t} and @code{uintptr_t}, which are integer types big
119 enough to hold a pointer.
120
121 On all systems, this header defines types @code{intmax_t} and
122 @code{uintmax_t}, which are the system's signed and unsigned integer
123 types with the widest ranges.
124
125 For every signed integer type @code{@var{type}_t} it defines, as well
126 as for @code{ptrdiff_t} defined in @file{<stddef.h>}, this header also
127 defines macros @code{@var{type}_MAX} and @code{@var{type}_MIN} that
128 give the type's range.  Similarly, for every unsigned integer type
129 @code{@var{type}_t} defined here, as well as for @code{size_t} defined
130 in @file{<stddef.h>}, this header defines a @code{@var{type}_MAX}
131 macro giving its maximum value.
132
133 @item <inttypes.h>
134 @file{<stdint.h>} is useful on its own, but it provides no way to pass
135 the types it defines to @func{printf} and related functions.  This
136 header provides macros to help with that.  For every
137 @code{int@var{n}_t} defined by @file{<stdint.h>}, it provides macros
138 @code{PRId@var{n}} and @code{PRIi@var{n}} for formatting values of
139 that type with @code{"%d"} and @code{"%i"}.  Similarly, for every
140 @code{uint@var{n}_t}, it provides @code{PRIo@var{n}},
141 @code{PRIu@var{n}}, @code{PRIu@var{x}}, and @code{PRIu@var{X}}.
142
143 You use these something like this, taking advantage of the fact that
144 the C compiler concatenates adjacent string literals:
145 @example
146 #include <inttypes.h>
147 @dots{}
148 int32_t value = @dots{};
149 printf ("value=%08"PRId32"\n", value);
150 @end example
151 @noindent
152 The @samp{%} is not supplied by the @code{PRI} macros.  As shown
153 above, you supply it yourself and follow it by any flags, field
154 widths, etc.
155
156 @item <stdio.h>
157 The @func{printf} function has some new type modifiers for printing
158 standard types:
159
160 @table @samp
161 @item j
162 For @code{intmax_t} (e.g.@: @samp{%jd}) or @code{uintmax_t} (e.g.@:
163 @samp{%ju}).
164
165 @item z
166 For @code{size_t} (e.g.@: @samp{%zu}).
167
168 @item t
169 For @code{ptrdiff_t} (e.g.@: @samp{%td}).
170 @end table
171
172 Pintos @func{printf} also implements a nonstandard @samp{'} flag that
173 group large numbers with commas to make them easier to read.
174 @end table
175
176 @node Unsafe String Functions
177 @section Unsafe String Functions
178
179 A few of the string functions declared in the standard
180 @file{<string.h>} and @file{<stdio.h>} headers are notoriously unsafe.
181 The worst offenders are intentionally not included in the Pintos C
182 library:
183
184 @table @func
185 @item strcpy
186 When used carelessly this function can overflow the buffer reserved
187 for its output string.  Use @func{strlcpy} instead.  Refer to
188 comments in its source code in @code{lib/string.c} for documentation.
189
190 @item strncpy
191 This function can leave its destination buffer without a null string
192 terminator and it has performance problems besides.  Again, use
193 @func{strlcpy}.
194
195 @item strcat
196 Same issue as @func{strcpy}, but substitute @func{strlcat}.
197 Again, refer to comments in its source code in @code{lib/string.c} for
198 documentation.
199
200 @item strncat
201 The meaning of its buffer size argument often leads to problems.
202 Again, use @func{strlcat}.
203
204 @item strtok
205 Uses global data, so it is unsafe in threaded programs such as
206 kernels.  Use @func{strtok_r} instead, and see its source code in
207 @code{lib/string.c} for documentation and an example.
208
209 @item sprintf
210 Same issue as @func{strcpy}.  Use @func{snprintf} instead.  Refer
211 to comments in @code{lib/stdio.h} for documentation.
212
213 @item vsprintf
214 Same issue as @func{strcpy}.  Use @func{vsnprintf} instead.
215 @end table
216
217 If you try to use any of these functions, you should get a hint from
218 the error message, which will refer to an identifier like
219 @code{dont_use_sprintf_use_snprintf}.