Point out that the tarball does not include the doc directory.
[pintos-anon] / doc / standards.texi
1 @node Coding Standards
2 @appendix Coding Standards
3
4 All of you should have taken a class like CS 107, so we expect you to be
5 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 described there.
10
11 Our standards for coding are most important for grading.  We want to
12 stress that aside from the fact that we are explicitly basing part of
13 your grade on these things, good coding practices will improve the
14 quality of your code.  This makes it easier for your partners to
15 interact with it, and ultimately, will improve your chances of having a
16 good working program.  That said once, the rest of this document will
17 discuss only the ways in which our coding standards will affect our
18 grading.
19
20 @menu
21 * Coding Style::                
22 * C99::                         
23 * Unsafe String Functions::     
24 @end menu
25
26 @node Coding Style
27 @section Style
28
29 Style, for the purposes of our grading, refers to how readable your
30 code is.  At minimum, this means that your code is well formatted, your
31 variable names are descriptive and your functions are decomposed and
32 well commented.  Any other factors which make it hard (or easy) for us
33 to read or use your code will be reflected in your style grade.
34
35 The existing Pintos code is written in the GNU style and largely
36 follows the @uref{http://www.gnu.org/prep/standards_toc.html, , GNU
37 Coding Standards}.  We encourage you to follow the applicable parts of
38 them too, especially chapter 5, ``Making the Best Use of C.''  Using a
39 different style won't cause actual problems, but it's ugly to see
40 gratuitous differences in style from one function to another.  If your
41 code is too ugly, it will cost you points.
42
43 Please limit C source file lines to at most 79 characters long.
44
45 Pintos comments sometimes refer to external standards or
46 specifications by writing a name inside square brackets, like this:
47 @code{[IA32-v3a]}.  These names refer to the reference names used in
48 this documentation (@pxref{Bibliography}).
49
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.
54
55 We're only going to do a compile in the directory for the project being
56 submitted.  You don't need to make sure that the previous projects also
57 compile.
58
59 Project code should be written so that all of the subproblems for the
60 project function together, that is, without the need to rebuild with
61 different macros defined, etc.  If you do extra credit work that
62 changes normal Pintos behavior so as to interfere with grading, then
63 you must implement it so that it only acts that way when given a
64 special command-line option of the form @option{-@var{name}}, where
65 @var{name} is a name of your choice.  You can add such an option by
66 modifying @func{parse_options} in @file{threads/init.c}.
67
68 The introduction describes additional coding style requirements
69 (@pxref{Design}).
70
71 @node C99
72 @section C99
73
74 The Pintos source code uses a few features of the ``C99'' standard
75 library that were not in the original 1989 standard for C.  Many
76 programmers are unaware of these feature, so we will describe them.  The
77 new features used in Pintos are
78 mostly in new headers:
79
80 @table @file
81 @item <stdbool.h>
82 Defines macros @code{bool}, a 1-bit type that takes on only the values
83 0 and 1, @code{true}, which expands to 1, and @code{false}, which
84 expands to 0.
85
86 @item <stdint.h>
87 On systems that support them, this header defines types
88 @code{int@var{n}_t} and @code{uint@var{n}_t} for @var{n} = 8, 16, 32,
89 64, and possibly other values.  These are 2's complement signed and unsigned
90 types, respectively, with the given number of bits.  
91
92 On systems where it is possible, this header also defines types
93 @code{intptr_t} and @code{uintptr_t}, which are integer types big
94 enough to hold a pointer.
95
96 On all systems, this header defines types @code{intmax_t} and
97 @code{uintmax_t}, which are the system's signed and unsigned integer
98 types with the widest ranges.
99
100 For every signed integer type @code{@var{type}_t} defined here, as well
101 as for @code{ptrdiff_t} defined in @file{<stddef.h>}, this header also
102 defines macros @code{@var{TYPE}_MAX} and @code{@var{TYPE}_MIN} that
103 give the type's range.  Similarly, for every unsigned integer type
104 @code{@var{type}_t} defined here, as well as for @code{size_t} defined
105 in @file{<stddef.h>}, this header defines a @code{@var{TYPE}_MAX}
106 macro giving its maximum value.
107
108 @item <inttypes.h>
109 @file{<stdint.h>} provides no straightforward way to format
110 the types it defines with @func{printf} and related functions.  This
111 header provides macros to help with that.  For every
112 @code{int@var{n}_t} defined by @file{<stdint.h>}, it provides macros
113 @code{PRId@var{n}} and @code{PRIi@var{n}} for formatting values of
114 that type with @code{"%d"} and @code{"%i"}.  Similarly, for every
115 @code{uint@var{n}_t}, it provides @code{PRIo@var{n}},
116 @code{PRIu@var{n}}, @code{PRIu@var{x}}, and @code{PRIu@var{X}}.
117
118 You use these something like this, taking advantage of the fact that
119 the C compiler concatenates adjacent string literals:
120 @example
121 #include <inttypes.h>
122 @dots{}
123 int32_t value = @dots{};
124 printf ("value=%08"PRId32"\n", value);
125 @end example
126 @noindent
127 The @samp{%} is not supplied by the @code{PRI} macros.  As shown
128 above, you supply it yourself and follow it by any flags, field
129 width, etc.
130
131 @item <stdio.h>
132 The @func{printf} function has some new type modifiers for printing
133 standard types:
134
135 @table @samp
136 @item j
137 For @code{intmax_t} (e.g.@: @samp{%jd}) or @code{uintmax_t} (e.g.@:
138 @samp{%ju}).
139
140 @item z
141 For @code{size_t} (e.g.@: @samp{%zu}).
142
143 @item t
144 For @code{ptrdiff_t} (e.g.@: @samp{%td}).
145 @end table
146
147 Pintos @func{printf} also implements a nonstandard @samp{'} flag that
148 groups large numbers with commas to make them easier to read.
149 @end table
150
151 @node Unsafe String Functions
152 @section Unsafe String Functions
153
154 A few of the string functions declared in the standard
155 @file{<string.h>} and @file{<stdio.h>} headers are notoriously unsafe.
156 The worst offenders are intentionally not included in the Pintos C
157 library:
158
159 @table @func
160 @item strcpy
161 When used carelessly this function can overflow the buffer reserved
162 for its output string.  Use @func{strlcpy} instead.  Refer to
163 comments in its source code in @code{lib/string.c} for documentation.
164
165 @item strncpy
166 This function can leave its destination buffer without a null string
167 terminator.  It also has performance problems.  Again, use
168 @func{strlcpy}.
169
170 @item strcat
171 Same issue as @func{strcpy}.  Use @func{strlcat} instead.
172 Again, refer to comments in its source code in @code{lib/string.c} for
173 documentation.
174
175 @item strncat
176 The meaning of its buffer size argument is surprising.
177 Again, use @func{strlcat}.
178
179 @item strtok
180 Uses global data, so it is unsafe in threaded programs such as
181 kernels.  Use @func{strtok_r} instead, and see its source code in
182 @code{lib/string.c} for documentation and an example.
183
184 @item sprintf
185 Same issue as @func{strcpy}.  Use @func{snprintf} instead.  Refer
186 to comments in @code{lib/stdio.h} for documentation.
187
188 @item vsprintf
189 Same issue as @func{strcpy}.  Use @func{vsnprintf} instead.
190 @end table
191
192 If you try to use any of these functions, the error message will give
193 you a hint by referring to an identifier like
194 @code{dont_use_sprintf_use_snprintf}.