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 Please limit C source file lines to at most 79 characters long.
47 Pintos comments sometimes refer to external standards or
48 specifications by writing a name inside square brackets, like this:
49 @code{[IA32-v3]}. These names refer to the reference names used in
50 this documentation (@pxref{References}).
52 If you remove existing Pintos code, please delete it from your source
53 file entirely. Don't just put it into a comment or a conditional
54 compilation directive, because that makes the resulting code hard to
55 read. We're only going to do a compile in the directory for the current
56 project, so you don't need to make sure that the previous projects also
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{-o @var{name}}, where
65 @var{name} is a name of your choice. You can add such an option by
66 modifying @func{argv_init} in @file{threads/init.c}.
71 The Pintos source code uses a few features of the ``C99'' standard
72 library that were not in the original 1989 standard for C. Because
73 they are so new, most classes do not cover these features, so this
74 section will describe them. The new features used in Pintos are
75 mostly in new headers:
79 Defines macros @code{bool}, a 1-bit type that takes on only the values
80 0 and 1, @code{true}, which expands to 1, and @code{false}, which
84 On systems that support them, this header defines types
85 @code{int@var{n}_t} and @code{uint@var{n}_t} for @var{n} = 8, 16, 32,
86 64, and possibly others. These are 2's complement signed and unsigned
87 types, respectively, with the given number of bits.
89 On systems where it is possible, this header also defines types
90 @code{intptr_t} and @code{uintptr_t}, which are integer types big
91 enough to hold a pointer.
93 On all systems, this header defines types @code{intmax_t} and
94 @code{uintmax_t}, which are the system's signed and unsigned integer
95 types with the widest ranges.
97 For every signed integer type @code{@var{type}_t} it defines, as well
98 as for @code{ptrdiff_t} defined in @file{<stddef.h>}, this header also
99 defines macros @code{@var{type}_MAX} and @code{@var{type}_MIN} that
100 give the type's range. Similarly, for every unsigned integer type
101 @code{@var{type}_t} defined here, as well as for @code{size_t} defined
102 in @file{<stddef.h>}, this header defines a @code{@var{type}_MAX}
103 macro giving its maximum value.
106 @file{<stdint.h>} is useful on its own, but it provides no way to pass
107 the types it defines to @func{printf} and related functions. This
108 header provides macros to help with that. For every
109 @code{int@var{n}_t} defined by @file{<stdint.h>}, it provides macros
110 @code{PRId@var{n}} and @code{PRIi@var{n}} for formatting values of
111 that type with @code{"%d"} and @code{"%i"}. Similarly, for every
112 @code{uint@var{n}_t}, it provides @code{PRIo@var{n}},
113 @code{PRIu@var{n}}, @code{PRIu@var{x}}, and @code{PRIu@var{X}}.
115 You use these something like this, taking advantage of the fact that
116 the C compiler concatenates adjacent string literals:
118 #include <inttypes.h>
120 int32_t value = @dots{};
121 printf ("value=%08"PRId32"\n", value);
124 The @samp{%} is not supplied by the @code{PRI} macros. As shown
125 above, you supply it yourself and follow it by any flags, field
129 The @func{printf} function has some new type modifiers for printing
134 For @code{intmax_t} (e.g.@: @samp{%jd}) or @code{uintmax_t} (e.g.@:
138 For @code{size_t} (e.g.@: @samp{%zu}).
141 For @code{ptrdiff_t} (e.g.@: @samp{%td}).
144 Pintos @func{printf} also implements a nonstandard @samp{'} flag that
145 group large numbers with commas to make them easier to read.
148 @node Unsafe String Functions
149 @section Unsafe String Functions
151 A few of the string functions declared in the standard
152 @file{<string.h>} and @file{<stdio.h>} headers are notoriously unsafe.
153 The worst offenders are intentionally not included in the Pintos C
158 When used carelessly this function can overflow the buffer reserved
159 for its output string. Use @func{strlcpy} instead. Refer to
160 comments in its source code in @code{lib/string.c} for documentation.
163 This function can leave its destination buffer without a null string
164 terminator and it has performance problems besides. Again, use
168 Same issue as @func{strcpy}. Use @func{strlcat} instead.
169 Again, refer to comments in its source code in @code{lib/string.c} for
173 The meaning of its buffer size argument often leads to problems.
174 Again, use @func{strlcat}.
177 Uses global data, so it is unsafe in threaded programs such as
178 kernels. Use @func{strtok_r} instead, and see its source code in
179 @code{lib/string.c} for documentation and an example.
182 Same issue as @func{strcpy}. Use @func{snprintf} instead. Refer
183 to comments in @code{lib/stdio.h} for documentation.
186 Same issue as @func{strcpy}. Use @func{vsnprintf} instead.
189 If you try to use any of these functions, you should get a hint from
190 the error message, which will refer to an identifier like
191 @code{dont_use_sprintf_use_snprintf}.