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