pintos-os.org Git - pintos-anon/blob - 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}.