-@node Coding Standards, Project Documentation, Multilevel Feedback Scheduling, Top
+@node Coding Standards
@appendix Coding Standards
-All of you should have taken a class like CS 107, so we expect you to
-be familiar with some set of coding standards such as
-@uref{http://www.stanford.edu/class/cs140/projects/misc/CodingStandards.pdf,
-, CS 107 Coding Standards}. Even if you've taken 107, we recommend
-reviewing that document. We expect code at the "Peer-Review Quality"
-level as described there.
-
-Our standards for coding are mostly important in grading. More
-information on our grading methodology can be found on the Course Info
-page and the Grading page. We also want to stress that aside from the
-fact that we are explicitly basing part of your grade on these things,
-good coding practices will improve the quality of your code. This
-makes it easier for your partners to interact with it, and ultimately,
-will improve your chances of having a good working program. That said
-once, the rest of this document will discuss only the ways in which
-our coding standards will affect our grading.
+@localcodingstandards{}
+
+Our standards for coding are most important for grading. We want to
+stress that aside from the fact that we are explicitly basing part of
+your grade on these things, good coding practices will improve the
+quality of your code. This makes it easier for your partners to
+interact with it, and ultimately, will improve your chances of having a
+good working program. That said once, the rest of this document will
+discuss only the ways in which our coding standards will affect our
+grading.
@menu
* Coding Style::
-* Conditional Compilation::
* C99::
* Unsafe String Functions::
@end menu
Pintos comments sometimes refer to external standards or
specifications by writing a name inside square brackets, like this:
-@code{[IA32-v3]}. These names refer to the reference names used in
-this documentation (@pxref{References}).
+@code{[IA32-v3a]}. These names refer to the reference names used in
+this documentation (@pxref{Bibliography}).
If you remove existing Pintos code, please delete it from your source
file entirely. Don't just put it into a comment or a conditional
compilation directive, because that makes the resulting code hard to
-read. We're only going to do a compile in the directory for the current
-project, so you don't need to make sure that the previous projects also
-compile.
-
-@node Conditional Compilation
-@section Conditional Compilation
+read.
-Given the scope and complexity of your assignments this quarter, you
-may find it convenient while coding and debugging (and we will find it
-convenient while grading) to be able to independently turn different
-parts of the assignments on and off. To do this, choose a macro name
-and use it in conditional
-compilation directives, e.g.:
+We're only going to do a compile in the directory for the project being
+submitted. You don't need to make sure that the previous projects also
+compile.
-@example
-#ifdef @var{NAME}
-@dots{}your code@dots{}
-#endif
-@end example
+Project code should be written so that all of the subproblems for the
+project function together, that is, without the need to rebuild with
+different macros defined, etc. If you do extra credit work that
+changes normal Pintos behavior so as to interfere with grading, then
+you must implement it so that it only acts that way when given a
+special command-line option of the form @option{-@var{name}}, where
+@var{name} is a name of your choice. You can add such an option by
+modifying @func{parse_options} in @file{threads/init.c}.
-In general, the code that you turn in must not depend on conditional
-compilation directives. Project code should be written so that all of
-the subproblems for the project function together, and it should
-compile properly without the need for any new macros to be defined.
-There are a few exceptions:
-
-@itemize @bullet
-@item
-Problem 1-4, the advanced scheduler. We must be able to turn this on
-and off with a compile-time directive. You must use the macro name we
-specify for that part. @xref{Problem 1-4 Advanced Scheduler}, for
-details.
-
-@item
-Problem 3-2, paging to and from disk. Your page replacement policy must
-default to LRU-like replacement, but we must be able to choose a random
-replacement policy with a compile-time directive. You must use the
-macro name we specify for that part. @xref{Problem 3-2 Paging To and
-From Disk}, for details.
-
-@item
-Code written for extra credit may be included conditionally. If the
-extra credit code changes the normally expected functionality of the
-code, then it @emph{must} be included conditionally, and it must not
-be enabled by default.
-@end itemize
-
-You can use @file{constants.h} in @file{pintos/src} to define macros
-for conditional compilation. We will replace the @file{constants.h}
-that you supply with one of our own when we test your code, so do not
-define anything important in it.
+The introduction describes additional coding style requirements
+(@pxref{Design}).
@node C99
@section C99
The Pintos source code uses a few features of the ``C99'' standard
-library that were not in the original 1989 standard for C. Because
-they are so new, most classes do not cover these features, so this
-section will describe them. The new features used in Pintos are
+library that were not in the original 1989 standard for C. Many
+programmers are unaware of these feature, so we will describe them. The
+new features used in Pintos are
mostly in new headers:
@table @file
@item <stdint.h>
On systems that support them, this header defines types
@code{int@var{n}_t} and @code{uint@var{n}_t} for @var{n} = 8, 16, 32,
-64, and possibly others. These are 2's complement signed and unsigned
+64, and possibly other values. These are 2's complement signed and unsigned
types, respectively, with the given number of bits.
On systems where it is possible, this header also defines types
@code{uintmax_t}, which are the system's signed and unsigned integer
types with the widest ranges.
-For every signed integer type @code{@var{type}_t} it defines, as well
+For every signed integer type @code{@var{type}_t} defined here, as well
as for @code{ptrdiff_t} defined in @file{<stddef.h>}, this header also
-defines macros @code{@var{type}_MAX} and @code{@var{type}_MIN} that
+defines macros @code{@var{TYPE}_MAX} and @code{@var{TYPE}_MIN} that
give the type's range. Similarly, for every unsigned integer type
@code{@var{type}_t} defined here, as well as for @code{size_t} defined
-in @file{<stddef.h>}, this header defines a @code{@var{type}_MAX}
+in @file{<stddef.h>}, this header defines a @code{@var{TYPE}_MAX}
macro giving its maximum value.
@item <inttypes.h>
-@file{<stdint.h>} is useful on its own, but it provides no way to pass
-the types it defines to @func{printf} and related functions. This
+@file{<stdint.h>} provides no straightforward way to format
+the types it defines with @func{printf} and related functions. This
header provides macros to help with that. For every
@code{int@var{n}_t} defined by @file{<stdint.h>}, it provides macros
@code{PRId@var{n}} and @code{PRIi@var{n}} for formatting values of
@noindent
The @samp{%} is not supplied by the @code{PRI} macros. As shown
above, you supply it yourself and follow it by any flags, field
-widths, etc.
+width, etc.
@item <stdio.h>
The @func{printf} function has some new type modifiers for printing
@end table
Pintos @func{printf} also implements a nonstandard @samp{'} flag that
-group large numbers with commas to make them easier to read.
+groups large numbers with commas to make them easier to read.
@end table
@node Unsafe String Functions
The worst offenders are intentionally not included in the Pintos C
library:
-@table @func
+@table @code
@item strcpy
When used carelessly this function can overflow the buffer reserved
for its output string. Use @func{strlcpy} instead. Refer to
@item strncpy
This function can leave its destination buffer without a null string
-terminator and it has performance problems besides. Again, use
+terminator. It also has performance problems. Again, use
@func{strlcpy}.
@item strcat
documentation.
@item strncat
-The meaning of its buffer size argument often leads to problems.
+The meaning of its buffer size argument is surprising.
Again, use @func{strlcat}.
@item strtok
Same issue as @func{strcpy}. Use @func{vsnprintf} instead.
@end table
-If you try to use any of these functions, you should get a hint from
-the error message, which will refer to an identifier like
+If you try to use any of these functions, the error message will give
+you a hint by referring to an identifier like
@code{dont_use_sprintf_use_snprintf}.
projects / pintos-anon / blobdiff