📄 http:^^www.cs.wisc.edu^~glew^coding-standards.html
字号:
Date: Tue, 05 Nov 1996 00:16:27 GMTServer: NCSA/1.5Content-type: text/htmlLast-modified: Thu, 12 Sep 1996 23:37:54 GMTContent-length: 54366<HTML>$Header: /u/g/l/glew/public/html/RCS/coding-standards.html,v 1.2 1995/06/22 08:43:54 glew Exp $<TITLE>P6 C Coding Standards </TITLE><H1>P6 C Coding Standards </H1><HEAD>December 13, 1991<BR>P6 Architecture Group<BR>R. Wilkinson</HEAD><HR><H2>History</H2>EARLY DRAFTS - December 19, 1990; January 11, 1991<BR>FIRST RELEASE - January 29, 1991<BR>SECOND RELEASE - December 13, 1991Rev. 2.0<BR>Converted to HTML by A. Glew Thu Jun 22 1995<HR><H2>Introduction</H2>This document details the standards to be followed when writing <B>C</B> code.It is expected to be followed by all <B>C</B> programmersin the Workgroup Computing Division - Portland.By promulgating these standards,we hope to address software issues related to readability and maintainability.By conforming to a common layout,it will be significantly easier for members within the groupto navigate within one another's code.By not having to adjust to different coding formats,we remove a significant impediment to reading the code of others.In addition,the existence of some elements, such as standard function headers,will be an aid to others (and quite possibly the authors)in understanding what the program is doing.<P>Since even the simplest programs can take on lives of their own,it is recommended that these standards be followed from the earliest pointof program inception.The relatively small overhead incurred initiallywill be more than repaid over the life of the program.It should also be noted that code reviewsare intended to be part of our development methodology,and code is expected to conform to these standards to pass review.<P>While it is doubtful that everyone will be in agreementwith all of the standards presented,it is expected that they will be followed nonetheless.In all cases,good reasons exist for all of the standards in this document.The general intent is that within (and beyond) the context of these standards,code should be easily <I>readable</I> and <I>understandable</I>by any semi-<B>C</B>-literate programmer.This pertains not only to the format (and legibility) of <B>C</B> programs,but to the existence and helpfulness of comments within the code as well.<P><H2>Program Order</H2>The ordering of sections within programs will be as follows:<MENU><LI><CODE><Copyright></CODE> The Intel copyright notice.<LI> <CODE><RCS_id></CODE> The RCS id declaration.<LI> <CODE><overview></CODE> An overview of the file contents.<LI> <CODE><includes></CODE> Any file inclusions. Only definition files(".h") should be included.<LI><CODE><defines></CODE> Macro/constant definitions.<LI> <CODE>typedef/struct</CODE> Any type or structure definitions.<LI> <CODE><externs></CODE> Any external object definitions. Use with caution.<LI> <CODE><globals></CODE> All global variable declarations.<LI> <CODE><statics></CODE> All static variable declarations.<LI> <CODE><forwards></CODE> All forward function declarations.<LI> <CODE><functions></CODE> All function declarations (including "main").<LI> <CODE><RCS_log></CODE> RCS "Log" information.</MENU><P>These are discussed below.<DL><DT><Copyright><DD>To protect Intel's intellectual property,every file should have a copyright notice of the form:<PRE>/* Copyright Intel Corporation, 1990, 1991. */</PRE>Each year of development should be represented.<DT><RCS_id><DD>RCS header information should go at the beginning of all files.This should be of the form:<PRE> #ifndef lint static char *rcsid = "$Header: /u/g/l/glew/public/html/RCS/coding-standards.html,v 1.2 1995/06/22 08:43:54 glew Exp $"; #endif</PRE>In the case of header files,the form (for a header file called <CODE>chapeau.h</CODE>) should be:<PRE> #ifndef lint static char *rcsid_chapeau_h = "$Header: /u/g/l/glew/public/html/RCS/coding-standards.html,v 1.2 1995/06/22 08:43:54 glew Exp $"; #endif</PRE><DT><overview><DD>This section is a (block) commentthat should contain a general overview of the file's contents.What functionality does the file provide,how does it relate to other files (if part of a larger program),what are the major entry points, etc.,are all appropriate questions to answer here.<DT><includes><DD>This section contains the "<CODE>#include</CODE>"sof any necessary header files.<DT><defines><DD>This section contains any necessary "<CODE>#define</CODE>"s.<DT><CODE>typedef/struct</CODE>:<DD>>This section contains all <CODE>typedef</CODE>and/or <CODE>struct</CODE> definitions specified in the file.<DT><externs><DD>>This section contains all <CODE>extern</CODE>declarations specified in the file.<DT><globals><DD>This section contains all global variable declarationswith external visibility.<DT><statics><DD>This section contains all global variabledeclarations with restricted static (local) visibility.<DT><forwards><DD>This section contains all necessary"forward" function/procedure declarations.(These are routines which are referencedbefore their actual implementation is specified.)<DT><functions><DD>This section contains the "body" of the code.All routines (including <CODE>main()</CODE>) are placed here.<DT><RCS_log><DD>RCS log information should be placedat the end of all files.This should be of the form:<PRE> /* * $Log: coding-standards.html,v $ * Revision 1.2 1995/06/22 08:43:54 glew * *** empty log message *** * */</PRE></DL><P>Particularly in those cases where they are extensive,macro, constant, type, and structure definitionsmay be more effectively placed in a separate ".h" file.<H2>Header Files</H2>To avoid the potential problems caused by nested header files,the body of header files should be designed for conditional inclusion.The format of a header file called toupee.h is given below.Note the (required) use of the leading and trailing underscores.<PRE> #ifndef _TOUPEE_H_ #define _TOUPEE_H_ : <B><file body></B> : #endif /* _TOUPEE_H_ */</PRE>Irrespective of the above format,header files should <B>not</B> include variable declarations.The use of the facilities provided in the header file, <CODE>p6system.h</CODE>,is strongly encouraged.A copy (as of December 13, 1991) has been included in Appendix A.The file currently lives in <CODE>~p6/arch/src/util</CODE>.<H2>Names</H2>The use of capital letters in names is not a matter of choice.All <CODE>#define</CODE>s should have all letters capitalized.This includes the definitions of both constants and macros.All elements of an enumerated type should have the first letter capitalizedand all other letters lower case.All other names should consist entirely of lower case letters.Use of extraneous capital letters outside the bounds specified hererequire very strong justifications.<P>Names should be chosen to be reasonably descriptive.Underscores ("_") should be used as separators.Names of the form <CODE>GetCacheIndex</CODE> (or <CODE>getcacheindex</CODE>) are <B><STRONG>not</STRONG></B> acceptable.If lengthening a name increases clarity and/or understandability,the more descriptive name should be chosen.If this results in longer names, so be it.(Clearly we're assuming some bounds of reason.Using "<CODE>i</CODE>", "<CODE>j</CODE>", and "<CODE>k</CODE>",for indices in a "for" statementis pretty straightforward,while using "<CODE>the_five_bits_for_encoding_the_register_or_an_immediate_value</CODE>"is obvious insanity.)<P>Names that should be avoided are:<UL><LI>Names that might conflict with standard library names.<LI>Names that differ only in case (e.g. <CODE>foo</CODE> and <CODE>Foo</CODE> and <CODE>FOO</CODE>).<LI>Names that might look like each other (e.g. <CODE>x_1st</CODE> and <CODE>x_lst</CODE> <BR>[<CODE>x_"one"st</CODE> and <CODE>x_"el"st</CODE>]).<LI>Names that override declarations at a higher level.</UL>Procedures names should reflect what they <B>do</B>.Function names should reflect what they <B>return</B>.For functions returning only <CODE>TRUE</CODE>/<CODE>FALSE</CODE> values,a predicate form is recommended (e.g. <CODE>is_queue_empty(ready_queue_ptr)</CODE>,<CODE>is_ford(car)</CODE>).<P>Strong encouragement is given to naming variablesand parameters that are pointersin some manner that makes note of this quality.Some suggestions are:<MENU><LI><CODE>black_table_ptr</CODE><LI><CODE>head_p</CODE><LI><CODE>tailp</CODE><LI><CODE>filepp</CODE> (pointer to a pointer)<LI><CODE>proc_AD</CODE> (for you 960 freaks - <B>not recommended</B>)</MENU>Types, variables, and routines that stand a good chance of being usedoutside the file in which they are contained (via "include")should have their names prefixed with some stringthat will aid in finding them.Some examples would be '<CODE>btb_...</CODE>'for popular "branch target buffer" entitiesand '<CODE>dfa_...</CODE>' for items from the"<B>d</B>ata <B>f</B>low <B>a</B>nalyzer"that may experience a wider audience.<H2>Macros</H2>Macros provide a convenient mechanism for textual substitution.As a result of this, it is easy to introduce subtle bugswith the undisciplined use of macros.In the interests of avoiding such problems,the following restrictions are mandated.<P>Macro routines should have all elements passed explicitlyand should have parentheses around their usage in the definition.The use of local and global variables within macros is discouraged.Macros of the form:<PRE> #define CALC(i, j) i + j * k - l</PRE>are in express violation of this standard.The appropriate form should be:<PRE> #define CALC(i, j, k, l) ((i) + (j) * (k) - (l))</PRE><P>If a macro consists of multiple statements,they should be enclosed in curly brackets ("<CODE>{</CODE>" and "<CODE>}</CODE>")and should<I>not</I>be ended with a semicolon ("<CODE>;</CODE>").<P>In the interests of avoiding potential side effects,it is recommended that macros be written in such a way as to evaluatetheir parameters only once.<H2>Declaration Standard</H2>This section describes the allowable forms of declarations.Unless mentioned in this section,other forms of declarations should be avoided.(Function declarations are described in a separate section.)<P>For emumerations, the proper forms are:<PRE>typedef enum { <I><I>first</I></I>, <I>second</I>, <I>third</I> } <I>type_name</I>; /* * This form is acceptable if it fits easily on a single line * and the elements are self-explanatory. */typedef enum { <I>first</I>, /* Pertinent comment. (Not required.) */ <I>second</I>, /* Pertinent comment. (Not required.) */ <I>third</I> /* Pertinent comment. (Not required.) */} <I>type_name</I>; /* * This form should be used if the definition will not fit on * a single line or if individual elements require explanation. */typedef enum { <I>first</I>, <I>second</I>, <I>third</I>, <I>fourth</I>, <I>fifth</I>, <I>sixth</I>, <I>seventh</I>, <I>eighth</I>, <I>ninth</I>, <I>tenth</I>, <I>eleventh</I>, <I>twelfth</I>, <I>thirteenth</I>} <I>type_name</I>; /* * This form should be used for large numbers of * self-descriptive elements. */typedef enum { <I>first</I> = <I>initializer1</I>, <I>second</I> = <I>initializer2</I>, <I>third</I> = <I>initializer3</I>} <I>type_name</I>;</PRE><BR>For structures, the proper forms are:<BR><PRE>typedef struct { <I>type_name1</I> <I>field_name1</I>; /* Purpose/usage */ <I>type_name2</I> <I>field_name2</I>; /* * Particularly long and detailed explanation of the purpose/usage * of this field using remarkably long words and referencing dull, * dry tomes better left buried in the crypt from which they were * unearthed rather than be forced out into the light of day. */ <I>type_name3</I> <I>field_name3</I>; /* Purpose/usage */} <I>type_name</I>;typedef struct { unsigned <I>field_name1</I> : 16; /* Purpose/usage */ unsigned <I>field_name2</I> : 8; /* Purpose/usage */ unsigned : 2; /* Why unused? */ unsigned <I>field_name3</I> : 4; /* Particularly long comment regarding purpose/usage */ unsigned <I>field_name4</I> : 2; /* Purpose/usage */} <I>type_name</I>;</PRE><BR>And, of course, for simple declarations:<BR><PRE><I>type_name</I> <I>id</I>; /* Purpose/usage */<I>type_name</I> <I>id_1</I>, <I>id_2</I>;<I>type_name</I> <I>id_1</I> = <I>init</I>, <I>id_2</I> = <I>init</I>;</PRE>In the case of pointer declarations,the asterisk should be associated with the variable <I>name</I>,not the pointer <I>type</I>.To illustrate, the following is <B>wrong</B>:<PRE> int* index_ptr; /* WRONG */</PRE>Rather, the <B>proper</B> form is:<PRE> int *index_ptr; /* RIGHT */</PRE>Whether the asterisk is lined-up at the standard "tab" indentation levelor unindented by one space is a matter of programmer choice.To illustrate, both of the following are acceptable:<PRE> bool is_ready; int *next_widget; /* unindented */ char id;</PRE><BR>and:<BR><PRE> bool is_ready; int *next_widget; /* lined-up */ char id;</PRE>At no time should the fact that the compiler assigns enumeration valuesin a particular manner be used in a program.Rather than do this,explicit values should be associated with the elements in the declaration.<P>The use of bit fields to minimize storage usage(as opposed to mapping hardware structures)is strongly discouraged.<P>Unless truly obvious,comments should be included with each element of a structure.<P>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -