Recommended C Style and Coding StandardsL.W. CannonR.A. ElliottL.W. KirchhoffJ.H. MillerJ.M. MilnerR.W. MitzeE.P. SchanN.O. WhittingtonBell LabsHenry SpencerZoology Computer SystemsUniversity of TorontoDavid KeppelEECS, UC BerkeleyCS&E, University of WashingtonMark BraderSoftQuad IncorporatedTorontoABSTRACTThis document is an updated version of the Indian Hill C Style and Coding Stan-dards paper, with modifications by the last three authors. It describes a recommendedcoding standard for C programs. The scope is coding style, not functional organization.February 19, 1997Recommended C Style and Coding StandardsL.W. CannonR.A. ElliottL.W. KirchhoffJ.H. MillerJ.M. MilnerR.W. MitzeE.P. SchanN.O. WhittingtonBell LabsHenry SpencerZoology Computer SystemsUniversity of TorontoDavid KeppelEECS, UC BerkeleyCS&E, University of WashingtonMark BraderSoftQuad IncorporatedToronto1. IntroductionThis document is a modified version of a document from a committee formed at AT&T’s Indian Hilllabs to establish a common set of coding standards and recommendations for the Indian Hill community.The scope of this work is C coding style. Good style should encourage consistent layout, improve portabil-ity, and reduce errors. This work does not cover functional organization, or general issues such as the useof gotos. We1have tried to combine previous work [1,6,8] on C style into a uniform set of standards thatshould be appropriate for any project using C, although parts are biased towards particular systems. Ofnecessity, these standards cannot cover all situations. Experience and informed judgement count for much.Programmers who encounter unusual situations should consult either experienced C programmers or codewritten by experienced C programmers (preferably following these rules).The standards in this document are not of themselves required, but individual institutions or groupsmay adopt part or all of them as a part of program acceptance. It is therefore likely that others at your insti-tution will code in a similar style. Ultimately, the goal of these standards is to increase portability, reducemaintenance, and above all improve clarity.Many of the style choices here are somewhat arbitrary. Mixed coding style is harder to maintainthan bad coding style. When changing existing code it is better to conform to the style (indentation, spac-ing, commenting, naming conventions) of the existing code than it is to blindly follow this document.‘‘To be clear is professional; not to be clear is unprofessional.’’ — Sir Ernest Gowers.1. The opinions in this document do not reflect the opinions of all authors. This is still an evolving document. Please send com-ments and suggestions to [email protected] or {rutgers,cornell,ucsd,ubc-cs,tektronix}!uw-beaver!june!pardoRecommended C Coding Standards Revision: 6.0 25 June 1990- 2 -2. File OrganizationA file consists of various sections that should be separated by several blank lines. Although there isno maximum length limit for source files, files with more than about 1000 lines are cumbersome to dealwith. The editor may not have enough temp space to edit the file, compilations will go more slowly, etc.Many rows of asterisks, for example, present little information compared to the time it takes to scroll past,and are discouraged. Lines longer than 79 columns are not handled well by all terminals and should beavoided if possible. Excessively long lines which result from deep indenting are often a symptom ofpoorly-organized code.2.1. File Naming ConventionsFile names are made up of a base name, and an optional period and suffix. The first character of thename should be a letter and all characters (except the period) should be lower-case letters and numbers.The base name should be eight or fewer characters and the suffix should be three or fewer characters (four,if you include the period). These rules apply to both program files and default files used and produced bythe program (e.g., ‘‘rogue.sav’’).Some compilers and tools require certain suffix conventions for names of files [5]. The followingsuffixes are required:C source file names must end in .cAssembler source file names must end in .sThe following conventions are universally followed:Relocatable object file names end in .oInclude header file names end in .h. An alternate convention that may be preferable in multi-language environments is to suffix both the language type and .h (e.g. ‘‘foo.c.h’’ or ‘‘foo.ch’’).Yacc source file names end in .yLex source file names end in .lC++ has compiler-dependent suffix conventions, including .c, ..c, .cc, .c.c, and .C. Since much Ccode is also C++ code, there is no clear solution here.In addition, it is conventional to use ‘‘Makefile’’ (not ‘‘makefile’’) for the control file for make (forsystems that support it) and ‘‘README’’ for a summary of the contents of the directory or directory tree.2.2. Program FilesThe suggested order of sections for a program file is as follows:1. First in the file is a prologue that tells what is in that file. A description of the purpose of the objectsin the files (whether they be functions, external data declarations or definitions, or something else) ismore useful than a list of the object names. The prologue may optionally contain author(s), revisioncontrol information, references, etc.2. Any header file includes should be next. If the include is for a non-obvious reason, the reason shouldbe commented. In most cases, system include files like stdio.h should be included before userinclude files.3. Any defines and typedefs that apply to the file as a whole are next. One normal order is to have‘‘constant’’ macros first, then ‘‘function’’ macros, then typedefs and enums.4. Next come the global (external) data declarations, usually in the order: externs, non-static globals,static globals. If a set of defines applies to a particular piece of global data (such as a flags word), thedefines should be immediately after the data declaration or embedded in structure declarations,indented to put the defines one level deeper than the first keyword of the declaration to which theyapply.5. The functions come last, and should be in some sort of meaningful order. Like functions shouldappear together. A ‘‘breadth-first’’ approach (functions on a similar level
View Full Document
Unlocking...