pintos-os.org Git - pintos-anon/blob - doc/standards.texi

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