Elements of Programming Style - The C Style Guide
January 23, 1996 Version 1.0
Neill Kipp
Files
Header Files Have a ".h" suffix. Header File Contains Class, Struct, And Union Declarations, Enum Declarations, #defines, TypeDefs.
Implementation Files Have a ".cc" (unix) or ".cpp" (Windows, DOS) SUFFIX. Implementation Files Contain Function and Method Implementations.
Make A Header Block in Header Files and Source Code Files. The Header Should Title, Author, Date, And Project Information As Well As A Simple Description of How The File Fits Into The Project.
Names of things
Names of Common C Characters
{Open Brace, Open Curly} Close Brace, Close (Open Parenthesis, Open Paren) Close Parenthesis, Close Paren [Open Bracket] Close Bracket.Period, Dot! Exclamation Point, Bang, Not | Bar, Vertical-Bar, OR, OR-bar (Actually a "Vertical Virgule) & ampersand, and, Reference, Ref * Asterisk, Multiply, Star, Pointer / Slash, Divide // Slash-Slash, Comment # points / backslash, (Sometimes" escape ") ~ Tilde
The Primitive Type Name "CHER" IS USUALLY PRONOUNCED LIKE The first syllable of "charcoal." Sometimes it is pronounced like "the" and some of the "and some of" car. "
Names and indentation
Names of naming convention
INTERSPERSED_UNDERSCORES LOWERCASEMixedCapital CapitalMixedCapital All_Uppercase
Applications of Naming Conventions
Enumeration_Item_name Variablename Typename, ClassName, MethodName () UnixFileName.cc DOSFN.CPP POUND_DEFINES
Self-Documenting Code
Use long names for Every Name in your program.
No Magic Numbers
Numeric Constants Besides 0 (and Sometimes 1) Are Not ALOWED. Use Constants Or #defines.
WHITESPACE
Space (What You get WHEN You Press SpaceBar) NEWLINE (SUBSTIS for 8 spaces) Space and Indentation
After an open brace, indent every subsequent line four spaces until the matching close brace. If an if, while, or for has no brace following, indent the next line two spaces. Indent lines which end in a colon backward two spaces (public, case). A space precedes and follows reserved words (if, else, class, struct) unless preceded or followed by indentation or newlines or special punctuation. A space precedes and follows operators and comparators (except unary operator bang is not followed by a space ). Pointer variants (ampersand, star) are preceded and followed by space in declarations. Pointer variants (ampersand, star) are preceded (but not followed) by a space in expressions. A space follows an open parenthesis.
Newline
NEWLINE PRECEDES An Open Brace in The Following: Class, Struct, Union, Enum, Method, Function A Close Brace for Method, Function, IF, Else, Do, For, WHILE, SWITCH. SEMI-COLON, THEN NEWLINE, THEN BLANK LINE AFTER CLOSE BRACE for Class, Struct, Union. Newline Follows An Open Brace.
Comments
Comments always begin at current indentation level with "//" and a space. No other construct may appear on the same line as a comment. Comments always preceed the construct they address. Use complete sentences in a comment. When describing a statement, comments May Be in the impression.
Above all, be guided by what pleases the eye. Be guided by what makes your code more readable.
Header File Example
// Module Name: classname.h
// Project: CS1344-1, 2 Course Notes // Author: Neill Kipp
// Date: January 1, 1996
// Description: this file presents examples of naming and
// Indentation Style In A C Class Declaration. This Title
// Information is minimal.
// the Following Prevents Files from Being Included
// twice. it is a naming exception design to emulate a file name
// (Period Is Not a name Character; Underscore IS).
#ifndef classname_h
#define classname_h
// this Directive Includes The Superclass Declaration.
#include "super.h"
// this Directive Includes another class decaration.
#include "other.h"
// The comment for an enumeration deflaration precedes the decaration.
ENUM overflowstate
{
// Each Item's Comment Precedes It at the Same Indentation as The Item.
NO_OVERFLOW,
// FOLLOW The Last Item with a comm (
// IT Helps Avoid Syntax Errors when adding or realranging items.
Overflow_occurred,
}
// this class shows how naming convention and comments are buying in a
// Simple Class Declaration. Whitespace Precedes and Follows Reserved
// Words (Like "public").
Class classname
{
// After a brace, Indent Four Spaces.
// The description of the variable "memberdata" goes here.
Int memberdata;
// if a line ends in single colon, Reverse-Indent Two Spaces.
PUBLIC:
// The Constructor Gives Initial Values To Member Data.
ClassName ();
// The Destructor Guarantees Clean DEAlLocation.
// The Tilde (~) IS Part of The Method Name. It is not an operator.
~ ClassName ();
// this method increments the Member Variable by The Value in "Howmuch"
// and returns true if overflow is detected (false ostherwise). Method
.
OverflowState IncrementMemberVariable (int howmuch);
// Prints Message About overflow.
Void Showoverflow (OverflowState overflow);
}
#ENDIF
Source Code File Example
// Module Name: classname.cc
// Project: CS1344-1, 2 Course Notes
// Author: neill kipp
// Date: January 1, 1996
// Description: this file presents examples of naming and
// Indentation Style In A C Class Implementation. This Title
// Information is minimal.
// This Directive Includes Header Information for the "classname" class.
#include "classname.h"
Classname ::
Classname ()
{
// Initialize MEMBER DATA (Statement Comments Are In The Imperative,
// and preceed the statement). Suggestion: Write the Comments First, THEN
// Write the code.
MEMBERDATA = 0;
}
// The return Type Appears on The First Line,
// Followed by the class name colon-color on the second,
// and finally the method name on the last. Then a newline, An Open Brace
// and the space after the open parenthesis. IT Helps
// The Eye catch the Type Name.
OverflowState
Classname ::
IncrementMembervariable (int howmuch)
{
// Check the overflow condition.
IF (TOO_BIG - MEMBERVARIABLE> HOWMUCH) {
// if overflow, return there overflow occurred.
Return overflow_occurred;
} else {
// OtherWise, return overflow is OK.
Return overflow_none;
}
}
// this code imports the showoverflow method.
Void
Classname ::
Showoverflow (OverflowState overflow)
{
// Switch is a reserved word. It is stocked by a space.
Switch (overflow) {
// Lines Ending in a Colon Reverse Indent Two Spaces.
Case No_overflow: // Display Message About No overflow.
COUT << "No overflow occurred./n";
Break;
Case overflow_occurred:
// Display Message That Overflow Occurred.
COUT << "Warning: Overflow Occurred./N";
Break;
}
}
Other Examples
// Note The spacing and indeentation in the for statement.
For (WhichItem = 0; Whichitem DOSMETHING (WhichItem); } // Bang is not followed by a space. While (! Semaphoreok ()) { DowaitForseMaphore (long_time);
