[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
We encourage you to keep your code readable to help your TAs grade you fairly. Some points from the projects are allocated to coding style to reflect this goal. In addition, we believe that encouraging legible code has several other benefits: Your partners will have an easier time interacting with your code, Bugs commonly occur in poorly structured, overly-complex code, and ultimately you will be forming good habits for future development. This section will provide some suggestions for writing readable code.
Style refers to how readable your code is. This means that your code is well formatted, your variable names are descriptive and your functions are decomposed and well commented.
The existing Pintos code is written in the GNU style and largely follows the GNU Coding Standards. We encourage you to follow the applicable parts of them too, especially chapter 5, "Making the Best Use of C." Using a different style won't cause actual problems, but it's ugly to see gratuitous differences in style from one function to another.
Please limit C source file lines to 80 characters long, to conform to the existing code.
Pintos comments sometimes refer to external standards or specifications by
writing a name inside square brackets, like this: [IA32-v3a]
. These
names refer to the reference names used in this documentation
(see section 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 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 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
-name
, where name is a name of your choice. You can add
such an option by modifying parse_options()
in threads/init.c
.
The introduction describes additional coding style guidelines (see section 1.2.2 Design).
The Pintos source code uses a few features of the "C99" standard 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:
<stdbool.h>
bool
, a 1-bit type that takes on only the values
0 and 1, true
, which expands to 1, and false
, which
expands to 0.
<stdint.h>
intn_t
and uintn_t
for n = 8, 16, 32,
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
intptr_t
and uintptr_t
, which are integer types big
enough to hold a pointer.
On all systems, this header defines types intmax_t
and
uintmax_t
, which are the system's signed and unsigned integer
types with the widest ranges.
For every signed integer type type_t
defined here, as well
as for ptrdiff_t
defined in <stddef.h>
, this header also
defines macros TYPE_MAX
and TYPE_MIN
that
give the type's range. Similarly, for every unsigned integer type
type_t
defined here, as well as for size_t
defined
in <stddef.h>
, this header defines a TYPE_MAX
macro giving its maximum value.
<inttypes.h>
<stdint.h>provides no straightforward way to format the types it defines with
printf()
and related functions. This
header provides macros to help with that. For every
intn_t
defined by <stdint.h>, it provides macros
PRIdn
and PRIin
for formatting values of
that type with "%d"
and "%i"
. Similarly, for every
uintn_t
, it provides PRIon
,
PRIun
, PRIux
, and PRIuX
.
You use these something like this, taking advantage of the fact that the C compiler concatenates adjacent string literals:
#include <inttypes.h> ... int32_t value = ...; printf ("value=%08"PRId32"\n", value); |
%is not supplied by the
PRI
macros. As shown
above, you supply it yourself and follow it by any flags, field
width, etc.
<stdio.h>
printf()
function has some new type modifiers for printing
standard types:
j
intmax_t
(e.g. %jd) or
uintmax_t
(e.g.
%ju).
z
size_t
(e.g. %zu).
t
ptrdiff_t
(e.g. %td).
Pintos printf()
also implements a nonstandard '
flag that
groups large numbers with commas to make them easier to read.
A few of the string functions declared in the standard
<string.h>
and <stdio.h>
headers are notoriously unsafe.
The worst offenders are intentionally not included in the Pintos C
library:
strcpy
strlcpy()
instead. Refer to
comments in its source code in lib/string.c
for documentation.
strncpy
strlcpy()
.
strcat
strcpy()
. Use strlcat()
instead.
Again, refer to comments in its source code in lib/string.c
for
documentation.
strncat
strlcat()
.
strtok
strtok_r()
instead, and see its source code in
lib/string.c
for documentation and an example.
sprintf
strcpy()
. Use snprintf()
instead. Refer
to comments in lib/stdio.h
for documentation.
vsprintf
strcpy()
. Use vsnprintf()
instead.
If you try to use any of these functions, the error message will give
you a hint by referring to an identifier like
dont_use_sprintf_use_snprintf
.
[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |