📄 x-coding3.html
字号:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"><html><head><link rel="STYLESHEET" type="text/css" href="wrs.css"><title> Coding Conventions </title></head><body bgcolor="FFFFFF"><p class="navbar" align="right"><a href="index.html"><img border="0" alt="[Contents]" src="icons/contents.gif"></a><a href="GuideIX.html"><img border="0" alt="[Index]" src="icons/index.gif"></a><a href="x-coding.html"><img border="0" alt="[Top]" src="icons/top.gif"></a><a href="x-coding2.html"><img border="0" alt="[Prev]" src="icons/prev.gif"></a><a href="GuideIX.html"><img border="0" alt="[Next]" src="icons/next.gif"></a></p><font face="Helvetica, sans-serif" class="sans"><h3 class="H2"><i><a name="84390">I.3 C Coding Conventions</a></i></h3></font><dl class="margin"><dl class="margin"><dd><p class="Body"><a name="84391"> </a>These conventions are divided into the following categories:</p></dl><dl class="margin"><ul class="BulletSingle" type="disc"><li><a name="84392"> </a>Module Layout</li></ul><ul class="BulletSingle" type="disc"><li><a name="84393"> </a>Subroutine Layout</li></ul><ul class="BulletSingle" type="disc"><li><a name="84394"> </a>Code Layout</li></ul><ul class="BulletSingle" type="disc"><li><a name="84395"> </a>Naming Conventions</li></ul><ul class="BulletSingle" type="disc"><li><a name="84396"> </a>Style</li></ul><ul class="BulletSingle" type="disc"><li><a name="84397"> </a>Header File Layout</li></ul><ul class="BulletSingle" type="disc"><li><a name="84398"> </a>Documentation Generation</li></ul></dl></dl><font face="Helvetica, sans-serif" class="sans"><h4 class="H3"><i><a name="84399">I.3.1 C Module Layout</a></i></h4></font><dl class="margin"><dl class="margin"><dd><p class="Body"><a name="84401"> </a>A <i class="term">module</i> is any unit of code that resides in a single source file. The conventions in this section define the standard module heading that must come at the beginning of every source module following the standard file heading. The module heading consists of the blocks described below; the blocks should be separated by one or more blank lines.</p><dd><p class="Body"><a name="84402"> </a>After the modification history and before the first function or executable code of the module, the following sections are included in the following order, if appropriate:</p></dl><dl class="margin"><p class="listspace"><ul class="Bullet" type="disc"><li><a name="84403"> </a><font face="Helvetica, sans-serif" size="-1" class="sans"><b class="hb">General Module Documentation:</b></font> The module documentation is a C comment consisting of a complete description of the overall module purpose and function, especially the external interface. The description includes the heading <i class="term">INCLUDE FILES:</i> followed by a list of relevant header files.</li></ul></p><p class="listspace"><ul class="Bullet" type="disc"><li><a name="84404"> </a><font face="Helvetica, sans-serif" size="-1" class="sans"><b class="hb">Includes:</b></font> The include block consists of a one-line C comment containing the word <i class="title">includes</i> followed by one or more C pre-processor <b class="keyword">#include</b> directives. This block groups all header files included in the module in one place.</li></ul></p><p class="listspace"><ul class="Bullet" type="disc"><li><a name="84405"> </a><font face="Helvetica, sans-serif" size="-1" class="sans"><b class="hb">Defines:</b></font> The defines block consists of a one-line C comment containing the word <i class="title">defines</i> followed by one or more C pre-processor <b class="keyword">#define</b> directives. This block groups all definitions made in the module in one place.</li></ul></p><p class="listspace"><ul class="Bullet" type="disc"><li><a name="84406"> </a><font face="Helvetica, sans-serif" size="-1" class="sans"><b class="hb">Typedefs:</b></font> The typedefs block consists of a one-line C comment containing the word <i class="title">typedefs</i> followed by one or more C <b class="keyword">typedef</b> statements, one per line. This block groups all type definitions made in the module in one place.</li></ul></p><p class="listspace"><ul class="Bullet" type="disc"><li><a name="84407"> </a><font face="Helvetica, sans-serif" size="-1" class="sans"><b class="hb">Globals:</b></font> The globals block consists of a one-line C comment containing the word <i class="title">globals</i> followed by one or more C declarations, one per line. This block groups together all declarations in the module that are intended to be visible outside the module.</li></ul></p><p class="listspace"><ul class="Bullet" type="disc"><li><a name="84408"> </a><font face="Helvetica, sans-serif" size="-1" class="sans"><b class="hb">Locals:</b></font> The locals block consists of a one-line C comment containing the word <i class="title">locals</i> followed by one or more C declarations, one per line. This block groups together all declarations in the module that are intended not to be visible outside the module.</li></ul></p><p class="listspace"><ul class="Bullet" type="disc"><li><a name="84409"> </a><font face="Helvetica, sans-serif" size="-1" class="sans"><b class="hb">Forward Declarations:</b></font> The forward declarations block consists of a one-line C comment containing the words <i class="title">forward declarations</i> followed by one or more ANSI C function prototypes, one per line. This block groups together all the function prototype definitions required in the module. Forward declarations must only apply to local functions; other types of functions belong in a header file.</li></ul></p></dl><dl class="margin"><dd><p class="Body"><a name="84410"> </a>The format of these blocks is shown in the following example (which also includes the file heading specified earlier).</p></dl></dl><h4 class="EntityTitle"><a name="84412"><font face="Helvetica, sans-serif" size="-1" class="sans">Example I-2: C File and Module Headings</font></a></h4><dl class="margin"><dl class="margin"><dd><pre class="Code"><b><a name="84413">/* fooLib.c - foo subroutine library */ /* Copyright 1984-1995 Wind River Systems, Inc. */ /* modification history -------------------- 02a,15sep92,nfs added defines MAX_FOOS and MIN_FATS. 01b,15feb86,dnw added routines fooGet() and fooPut(); added check for invalid index in fooFind(). 01a,10feb86,dnw written. */ /* DESCRIPTION This module is an example of the Wind River Systems C coding conventions. ... INCLUDE FILES: fooLib.h */ /* includes */ #include "vxWorks.h" #include "fooLib.h" /* defines */ #define MAX_FOOS 112 /* max # of foo entries */ #define MIN_FATS 2 * min # of FAT copies */ /* typedefs */ typedef struct fooMsg /* FOO_MSG */ { VOIDFUNCPTR func; /* pointer to function to invoke */ int arg [FOO_MAX_ARGS]; /* args for function */ } FOO_MSG; /* globals */ char * pGlobalFoo; /* global foo table */ /* locals */ LOCAL int numFoosLost; /* count of foos lost */ /* forward declarations */ LOCAL int fooMat (list * aList, int fooBar, BOOL doFoo); FOO_MSG fooNext (void); STATUS fooPut (FOO_MSG inPar); </a></b></pre></dl></dl><font face="Helvetica, sans-serif" class="sans"><h4 class="H3"><i><a name="84415">I.3.2 C Subroutine Layout</a></i></h4></font><dl class="margin"><dl class="margin"><dd><p class="Body"><a name="84417"> </a>The following conventions define the standard layout for every subroutine.</p><dd><p class="Body"><a name="84418"> </a>Each subroutine is preceded by a C comment heading consisting of documentation that includes the following blocks. There should be no blank lines in the heading, but each block should be separated with a line containing a single asterisk (*) in the first column.</p></dl><dl class="margin"><p class="listspace"><ul class="Bullet" type="disc"><li><a name="84419"> </a><font face="Helvetica, sans-serif" size="-1" class="sans"><b class="hb">Banner:</b></font> This is the start of a C comment and consists of a slash character (<b class="operator">/</b>) followed by 75 asterisks (<b class="operator">*</b>) across the page.</li></ul></p><p class="listspace"><ul class="Bullet" type="disc"><li><a name="84420"> </a><font face="Helvetica, sans-serif" size="-1" class="sans"><b class="hb">Title:</b></font> One line containing the routine name followed by a short, one-line description. The routine name in the title must match the declared routine name. This line becomes the title of automatically generated reference entries and indexes.</li></ul></p><p class="listspace"><ul class="Bullet" type="disc"><li><a name="84421"> </a><font face="Helvetica, sans-serif" size="-1" class="sans"><b class="hb">Description:</b></font> A full description of what the routine does and how to use it.</li></ul></p><p class="listspace"><ul class="Bullet" type="disc"><li><a name="84422"> </a><font face="Helvetica, sans-serif" size="-1" class="sans"><b class="hb">Returns:</b></font> The word <i class="term">RETURNS:</i> followed by a description of the possible result values of the subroutine. If there is no return value (as in the case of routines declared <b class="keyword">void</b>), enter:</li></ul></p><dl class="margin"><dd><pre class="Code2"><b><a name="84423">RETURNS: N/A</a></b></pre></dl><dl class="margin"><dd><div class="Indent"><a name="84424"> </a>Mention only true returns in this section--not values copied to a buffer given as an argument.</div><br></dl><p class="listspace"><ul class="Bullet" type="disc"><li><a name="84425"> </a><font face="Helvetica, sans-serif" size="-1" class="sans"><b class="hb">Error Number:</b></font> The word <i class="term">ERRNO:</i> followed by all possible <b class="symbol_lc">errno</b> values returned by the function. No description of the <b class="symbol_lc">errno</b> value is given, only the <b class="symbol_lc">errno</b> value and only in the form of a defined constant.<sup><a href="#foot"><b class="FootnoteMarker">1</b></a></sup></li></ul></p></dl><dl class="margin"><dd><p class="Body"><a name="84429"> </a>The subroutine documentation heading is terminated by the C end-of-comment character (<b class="operator">*/</b>), which must appear on a single line, starting in column one.</p><dd><p class="Body"><a name="84433"> </a>The subroutine declaration immediately follows the subroutine heading.<sup><a href="#foot"><b class="FootnoteMarker">2</b></a></sup> The format of the subroutine and parameter declarations is shown in <a href="x-coding3.html#84441"><i class="title">I.3.3 C Declaration Formats</i></a>.</p></dl></dl><h4 class="EntityTitle"><a name="84437"><font face="Helvetica, sans-serif" size="-1" class="sans">Example I-3: Standard C Subroutine Layout:</font></a></h4><dl class="margin"><dl class="margin"><dd><pre class="Code"><b><a name="84438">/******************************************************************** * * fooGet - get an element from a foo * * This routine finds the element of a specified index in a specified * foo. The value of the element found is copied to <pValue>. * * RETURNS: OK, or ERROR if the element is not found. * * ERRNO: * S_fooLib_BLAH * S_fooLib_GRONK */ STATUS fooGet ( FOO foo, /* foo in which to find element */ int index, /* element to be found in foo */ int * pValue /* where to put value */ ) { ... }</a></b></pre></dl></dl><font face="Helvetica, sans-serif" class="sans"><h4 class="H3"><i><a name="84441">I.3.3 C Declaration Formats</a></i></h4></font><dl class="margin"><dl class="margin"><dd><p class="Body"><a name="84442"> </a>Include only one declaration per line. Declarations are indented in accordance with <a href="x-coding3.html#84501"><i class="title">Indentation</i></a>, and are typed at the current indentation level.</p><dd><p class="Body"><a name="84446"> </a>The rest of this section describes the declaration formats for variables and subroutines.</p></dl></dl><font face="Helvetica, sans-serif" class="sans"><h4 class="H4"><i><a name="84447">Variables</a></i></h4></font><dl class="margin"><dl class="margin"><p class="listspace"><ul class="Bullet" type="disc"><li><a name="84449"> </a>For basic type variables, the type appears first on the line and is separated from the identifier by a tab. Complete the declaration with a meaningful one-line comment. For example:</li></ul></p><dl class="margin"><dd><pre class="Code2"><b><a name="84450">unsigned rootMemNBytes; /* memory for TCB and root stack */ int rootTaskId; /* root task ID */ BOOL roundRobinOn; /* boolean for round-robin mode */</a></b></pre></dl><p class="listspace"><ul class="Bullet" type="disc"><li><a name="84451"> </a>The <b class="symbol_lc">*</b> and <b class="symbol_lc">**</b> pointer declarators <i class="emphasis">belong</i> with the type. For example:</li></ul></p><dl class="margin"><dd><pre class="Code2"><b><a name="84452">FOO_NODE * pFooNode; /* foo node pointer */ FOO_NODE ** ppFooNode; /* pointer to the foo node pointer */</a></b></pre></dl><p class="listspace"><ul class="Bullet" type="disc"><li><a name="84453"> </a>Structures are formatted as follows: the keyword<b class="keyword"> struct</b> appears on the first line with the structure tag. The opening brace appears on the next line, followed by the elements of the structure. Each structure element is placed on a separate line with the appropriate indentation and comment. If necessary, the comments can extend over more than one line; see <a href="x-coding3.html#84526"><i class="title">Comments</i></a>, for details. The declaration is concluded by a line containing the closing brace, the type name, and the ending semicolon. Always define structures (and unions) with a <b class="keyword">typedef</b> declaration, and always include the structure tag as well as the type name. Never use a structure (or union) definition to declare a variable directly. The following is an example of acceptable style:</li></ul></p><dl class="margin"><dd><pre class="Code2"><b><a name="84457">typedef struct symtab /* SYMTAB - symbol table */ { OBJ_CORE objCore; /* object maintanance */ HASH_ID nameHashId; /* hash table for names */ SEMAPHORE symMutex; /* symbol table mutual exclusion sem */ PART_ID symPartId; /* memory partition id for symbols */ BOOL sameNameOk; /* symbol table name clash policy */ int nSymbols; /* current number of symbols in table */ } SYMTAB;</a></b></pre></dl><dl class="margin"><dd><div class="Indent"><a name="84458"> </a>This format is used for other composite type declarations such as <b class="keyword">union</b> and <b class="keyword">enum</b>.</div><br><dd><div class="Indent"><a name="84459"> </a>The exception to never using a structure definition to declare a variable directly is structure definitions that contain pointers to structures, which effectively declare another <b class="keyword">typedef</b>. This exception allows structures to store pointers to related structures without requiring the inclusion of a header that defines the type.</div><br><dd><div class="Indent"><a name="84460"> </a>For example, the following compiles without including the header that defines <b class="keyword">struct</b> <b class="symbol_lc">fooInfo</b> (so long as the surrounding code never delves inside this structure):<p class="table"><table border="0" cellpadding="0" cellspacing="0"><tr><td colspan="20"><hr class="tablerule"></td></tr><tr valign="top"><td colspan=1 rowspan=1><p class="BodyLeft"><a name="85062"> </a>CORRECT: </p></td><td colspan=1 rowspan=1><pre class="CodeLeft"><b><a name="85068">typedef struct tcbInfo { struct fooInfo * pfooInfo; ... } TCB_INFO;</a></b></pre></td></tr><tr><td colspan="20"><hr class="tablerule"></td></tr><tr valign="middle"><td colspan="20"></td></tr></table></p></div><br><dd><div class="Indent"><a name="84463"> </a>By contrast, the following cannot compile without including a header file to define the type <b class="symbol_UC">FOO_INFO</b>:<p class="table"><table border="0" cellpadding="0" cellspacing="0">⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -