-@node Coding Standards, Project Documentation, Multilevel Feedback Scheduling, Top
+@node Coding Standards, Project Documentation, 4.4BSD Scheduler, Top
@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
+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.
+reviewing that document. We expect code at the ``Peer-Review Quality''
+level described there.
+
+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
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
+read.
+
+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.
Project code should be written so that all of the subproblems for the
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{-o @var{name}}, where
+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{argv_init} in @file{threads/init.c}.
+modifying @func{parse_options} in @file{threads/init.c}.
+
+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
@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