1 @node Coding Standards, , 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::
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.
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.
42 @node Conditional Compilation
43 @section Conditional Compilation
45 Given the scope and complexity of your assignments this quarter, you
46 may find it convenient while coding and debugging (and we will find it
47 convenient while grading) to be able to independently turn different
48 parts of the assignments on and off. To do this, choose a macro name
49 and use it in conditional
50 compilation directives, e.g.:
54 @dots{}your code@dots{}
58 In general, the code that you turn in must not depend on conditional
59 compilation directives. Project code should be written so that all of
60 the subproblems for the project function together, and it should
61 compile properly without the need for any new macros to be defined.
62 There are a few exceptions:
66 Project 1 has a few parts that we must be able to turn on and off via
67 conditional compilation. You must use the macros we specify for those
71 Code written for extra credit may be included conditionally. If the
72 extra credit code changes the normally expected functionality of the
73 code, then it @emph{must} be included conditionally, and it must not
74 be enabled by default.
77 You can use @file{constants.h} in @file{pintos/src} to define macros
78 for conditional compilation. We will replace the @file{constants.h}
79 that you supply with one of our own when we test your code, so do not
80 define anything important in it.
85 The Pintos source code uses a few features of the ``C99'' standard
86 library that were not in the original 1989 standard for C. Because
87 they are so new, most classes do not cover these features, so this
88 section will describe them. The new features used in Pintos are
89 mostly in new headers:
93 Defines macros @code{bool}, a 1-bit type that takes on only the values
94 0 and 1, @code{true}, which expands to 1, and @code{false}, which
98 On systems that support them, this header defines types
99 @code{int@var{n}_t} and @code{uint@var{n}_t} for @var{n} = 8, 16, 32,
100 64, and possibly others. These are 2's complement signed and unsigned
101 types, respectively, with the given number of bits.
103 On systems where it is possible, this header also defines types
104 @code{intptr_t} and @code{uintptr_t}, which are integer types big
105 enough to hold a pointer.
107 On all systems, this header defines types @code{intmax_t} and
108 @code{uintmax_t}, which are the system's signed and unsigned integer
109 types with the widest ranges.
111 For every signed integer type @code{@var{type}_t} it defines, as well
112 as for @code{ptrdiff_t} defined in @file{<stddef.h>}, this header also
113 defines macros @code{@var{type}_MAX} and @code{@var{type}_MIN} that
114 give the type's range. Similarly, for every unsigned integer type
115 @code{@var{type}_t} defined here, as well as for @code{size_t} defined
116 in @file{<stddef.h>}, this header defines a @code{@var{type}_MAX}
117 macro giving its maximum value.
120 @file{<stdint.h>} is useful on its own, but it provides no way to pass
121 the types it defines to @code{printf()} and related functions. This
122 header provides macros to help with that. For every
123 @code{int@var{n}_t} defined by @file{<stdint.h>}, it provides macros
124 @code{PRId@var{n}} and @code{PRIi@var{n}} for formatting values of
125 that type with @code{"%d"} and @code{"%i"}. Similarly, for every
126 @code{uint@var{n}_t}, it provides @code{PRIo@var{n}},
127 @code{PRIu@var{n}}, @code{PRIu@var{x}}, and @code{PRIu@var{X}}.
129 You use these something like this, taking advantage of the fact that
130 the C compiler concatenates adjacent string literals:
132 #include <inttypes.h>
134 int32_t value = @dots{};
135 printf ("value=%08"PRId32"\n");
138 The @samp{%} is not supplied by the @code{PRI} macros. As shown
139 above, you supply it yourself and follow it by any flags, field
143 The @file{printf()} function has some new type modifiers for printing
148 For @code{intmax_t} (e.g.@: @samp{%jd}) or @code{uintmax_t} (e.g.@:
152 For @code{size_t} (e.g.@: @samp{%zu}).
155 For @code{ptrdiff_t} (e.g.@: @samp{%td}).
159 @node Unsafe String Functions
160 @section Unsafe String Functions
162 A few of the string functions declared in the standard
163 @file{<string.h>} and @file{<stdio.h>} headers are notoriously unsafe.
164 The worst offenders are intentionally not included in the Pintos C
169 When used carelessly this function can overflow the buffer reserved
170 for its output string. Use @code{strlcpy()} instead. Refer to
171 comments in its source code in @code{lib/string.c} for documentation.
174 This function can leave its destination buffer without a null string
175 terminator and it has performance problems besides. Again, use
179 Same issue as @code{strcpy()}, but substitute @code{strlcat()}.
180 Again, refer to comments in its source code in @code{lib/string.c} for
184 The meaning of its buffer size argument often leads to problems.
185 Again, use @code{strlcat()}.
188 Uses global data, so it is unsafe in threaded programs such as
189 kernels. Use @code{strtok_r()} instead, and see its source code in
190 @code{lib/string.c} for documentation and an example.
193 Same issue as @code{strcpy()}. Use @code{snprintf()} instead. Refer
194 to comments in @code{lib/stdio.h} for documentation.
197 Same issue as @code{strcpy()}. Use @code{vsnprintf()} instead.
200 If you try to use any of these functions, you should get a hint from
201 the error message, which will refer to an identifier like
202 @code{dont_use_sprintf_use_snprintf}.