X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?p=pintos-anon;a=blobdiff_plain;f=doc%2Fstandards.texi;h=8e4b3703432025bb5191ef4ccfca24ec503647c5;hp=28bfc81f12979d93a542ead5b6662493e7874993;hb=ed04361f6ec91e4f0db1550c2cc487a461b2d17b;hpb=98c2fc1ab7d395bb92cf4a57233fe432539d26a9 diff --git a/doc/standards.texi b/doc/standards.texi index 28bfc81..8e4b370 100644 --- a/doc/standards.texi +++ b/doc/standards.texi @@ -1,26 +1,21 @@ -@node Coding Standards, , 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 @node Coding Style @@ -37,55 +32,44 @@ follows the @uref{http://www.gnu.org/prep/standards_toc.html, , 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. +gratuitous differences in style from one function to another. If your +code is too ugly, it will cost you points. -@node Conditional Compilation -@section Conditional Compilation +Please limit C source file lines to at most 79 characters long. -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.: +Pintos comments sometimes refer to external standards or +specifications by writing a name inside square brackets, like this: +@code{[IA32-v3a]}. These names refer to the reference names used in +this documentation (@pxref{Bibliography}). -@example -#ifdef @var{NAME} -@dots{}your code@dots{} -#endif -@end example +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. -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 -Project 1 has a few parts that we must be able to turn on and off via -conditional compilation. You must use the macros we specify for those -parts. - -@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. +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 @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}. + +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 @@ -97,7 +81,7 @@ expands to 0. @item 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 @@ -108,17 +92,17 @@ On all systems, this header defines types @code{intmax_t} and @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{}, 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{}, this header defines a @code{@var{type}_MAX} +in @file{}, this header defines a @code{@var{TYPE}_MAX} macro giving its maximum value. @item -@file{} is useful on its own, but it provides no way to pass -the types it defines to @code{printf()} and related functions. This +@file{} 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{}, it provides macros @code{PRId@var{n}} and @code{PRIi@var{n}} for formatting values of @@ -132,15 +116,15 @@ the C compiler concatenates adjacent string literals: #include @dots{} int32_t value = @dots{}; -printf ("value=%08"PRId32"\n"); +printf ("value=%08"PRId32"\n", value); @end example @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 -The @file{printf()} function has some new type modifiers for printing +The @func{printf} function has some new type modifiers for printing standard types: @table @samp @@ -154,6 +138,9 @@ For @code{size_t} (e.g.@: @samp{%zu}). @item t For @code{ptrdiff_t} (e.g.@: @samp{%td}). @end table + +Pintos @func{printf} also implements a nonstandard @samp{'} flag that +groups large numbers with commas to make them easier to read. @end table @node Unsafe String Functions @@ -164,39 +151,39 @@ A few of the string functions declared in the standard The worst offenders are intentionally not included in the Pintos C library: -@table @code -@item strcpy() +@table @func +@item strcpy When used carelessly this function can overflow the buffer reserved -for its output string. Use @code{strlcpy()} instead. Refer to +for its output string. Use @func{strlcpy} instead. Refer to comments in its source code in @code{lib/string.c} for documentation. -@item strncpy() +@item strncpy This function can leave its destination buffer without a null string -terminator and it has performance problems besides. Again, use -@code{strlcpy()}. +terminator. It also has performance problems. Again, use +@func{strlcpy}. -@item strcat() -Same issue as @code{strcpy()}, but substitute @code{strlcat()}. +@item strcat +Same issue as @func{strcpy}. Use @func{strlcat} instead. Again, refer to comments in its source code in @code{lib/string.c} for documentation. -@item strncat() -The meaning of its buffer size argument often leads to problems. -Again, use @code{strlcat()}. +@item strncat +The meaning of its buffer size argument is surprising. +Again, use @func{strlcat}. -@item strtok() +@item strtok Uses global data, so it is unsafe in threaded programs such as -kernels. Use @code{strtok_r()} instead, and see its source code in +kernels. Use @func{strtok_r} instead, and see its source code in @code{lib/string.c} for documentation and an example. -@item sprintf() -Same issue as @code{strcpy()}. Use @code{snprintf()} instead. Refer +@item sprintf +Same issue as @func{strcpy}. Use @func{snprintf} instead. Refer to comments in @code{lib/stdio.h} for documentation. -@item vsprintf() -Same issue as @code{strcpy()}. Use @code{vsnprintf()} instead. +@item vsprintf +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}.