Coding Standards for C, C++, and Java

#ifndef MeaningfulNameH		// first line of the header file
#define MeaningfulNameH		// second line of the header file
	.
	.			// body of the header file
	.
#endif  // MeaningfulNameH	// last line of the header file; note comment

2.1 Descriptive Names

Names should be readable and self-documenting. Abbreviations and contractions are discouraged. Shorter synonyms are allowed when they follow common usage within the domain.

2.2 Valid Characters

All names should begin with a letter. Individual words in compound names are differentiated by capitalizing the first letter of each word as opposed to separating with an underscore. The use of special characters (anything other than letters and digits), including underscores is strongly discouraged. The first 31 characters of a name (including the prefix) must be unique, due to restrictions of various platforms. The uniqueness must not be due solely to a difference in case.

2.3 File Names

Filenames should only contain one period, to separate the file extension.

2.4 Function Names

Function names should preferably be an action verb. Boolean-valued functions (those that have two possible return values) should use the "is" prefix as in "isEmpty()".

2.5 Namespaces

Namespace collision should be minimized without introducing cryptic naming conventions by using the C++ namespace or Java package constructs.

3.1 Lines

3.1.1 Line Length

    cout << "This is an example of a line which must be wrapped, value = "
         << value << endl;

3.1.2 Statements Per Line

3.2 Comments

3.2.1 Automated Documentation Comments

    /**
      * This is a module, class, function, or instance variable comment
      * that will be extracted by an automated documentation tool.
      */

Such comments should be used to describe classes, methods, and global or instance variables.

3.2.2 Code Block Comments

3.2.3 Blank Lines

3.3 Formatting

3.3.1 Spacing Around Operators

	if ( value == 0 ) {		// right	
	if (value==0){			// not recommended

	void doIt( int v );		// right
	void doIt(int v);		// not recommended

	value = object->GetValue();	// right
	value=object -> GetValue();	// wrong

3.3.2 Indentation and Braces

	int main() {
		doSomething();
	}

	struct MyStruct {
		int x;
		int y;
	}

	if ( value == 0 ) {
		doSomething();
	} else if ( value == 2 ) {   // note position of cascaded if statement
		doSomething2();
	} else {
		doSomething3();
	}

	while ( value < 300 ) {
		doSomething();
	}

	do {
		doSomething();
	} while ( value < 300 )	     // note: ending brace and control on same line

	switch ( value ) {
	case 1:
		doSomething();
		break;
	case 2:
	case 3:
		doSomething2();
		break;
	default:
		break;		     // final break required
	}

3.3.3 Pointer and Reference Position

	char*	text;			// right
	char 	*text;			// not recommended

	char*	doSomething( int* x );	// right
	char	*doSomething( int *x );	// not recommended

3.4 Statements

3.4.1 Control Statements

	if ( value == 0 ) {		    // right
		doSomething();
	}

	if ( value == 0 ) doSomething();    // wrong - no block, not indented

	if (value == 0)
		doSomething();		    // wrong - no block

3.4.2 Conditional Statements

	int value = getValue();
	if ( value == 0 ) {		    // right
		doSomething();
	}
	if ( !value ) {			    // wrong - not explicit test
		doSomethingElse();
	}

	boolean value = getValue();
	if ( !value ) {			    // right - this is explicit
		doSomethingElse();	    // test for boolean type
	}

3.4.3 Include Statements

	#include <stdlib.h>			// right
	#include <stdio.h>			//			
	#include <Xm/Xm.h>			//
	#include "meaningfulname.h"		//

	#include "/proj/util/MeaningfulName.h"	// wrong - explicit path,
	#include <stdlib.h>			//  out of order,
	#include </usr/include/stdio.h>		//  path for system file,
	#include "Xm/Xm.h"	 		//  local include of library file 

3.5 Declarations

3.5.1 Variable Declaration

	int*	a;		// right
	int	b;		//
	int	c;		//
	double	d;		//
	double	e;		//

	double	a;		// right 
	int	b;		//

	double	d;		// acceptable - not grouped by type
	int	b;		//
	int*	a;		//
	double	e;		//
	int	c;		//
	
	int*	a, b, c;	// wrong - not individually declared, not
				// on separate lines

	int*	a,		// wrong - not individually declared
		b,		//   	
		c;		//  

3.5.2 External Variable Declaration

In the header file MeaningfulName.h,

	#ifdef MeaningfulNameInit     // the flag is called MeaningfulNameInit
	#define EXTERN		      // create the variable (only in main.cpp)
	#else
	#define EXTERN extern	      // just a reference (default) 
	#endif
	EXTERN ErrorLogger errorLog;
	#undef EXTERN

	#include meaningfulname.h	

	#define MeaningfulNameInit
	#include meaningfulname.h
	#undef MeaningfulNameInit

3.5.3 Numeric Constant Declaration

	const int    value  = A73B2X;	// right, hexadecimal constant
	const double evalue = 1.2E9;	// right, scientific notation constant

	const float  fvalue = 1.2e9;	// wrong, lowercase e

3.5.4 Enumerated Type Declaration

	enum CompassPoints {	// Enums used to specify direction.
		North = 0,	// 
		South = 1,	// 
		East  = 2,	// 
		West  = 3	//
	};

3.5.5 Struct and Union Declaration

	struct MeaningfulName {		// This is a struct of some data.
		int	firstInteger;	// This is the first int.
		int	secondInteger;	// This is the second int.
		double	firstDouble;	// This is the first double.
		double	secondDouble;	// This is the second double.
	};

3.5.6 Class Declaration

	class Value : public BaseValue {
	public:
		Value();			// Default constructor.
		Value( const Value& oldValue );	// Copy constructor.
		~Value();			// Destructor.
		void setValue( int newValue );	// Set value.
		int getValue();			// Get value.
 
	protected:
		void incrementValue();		// Increment value.

	private:
		int value;			// The value.
	};

4.1 Placement of Declarations

4.2 Switch Statements

4.3 Return Statements

4.4 Casts

4.5 Literals

const double PI = 3.141259;			// right
const char APP_NAME = "ACME Spreadsheet 1.0";	// right

area = 3.141259 * radius * radius;		// not recommended 
cout << "ACME Spreadsheet 1.0" << endl;		// not recommended

4.6 Explicit Initialization

4.7 Constructs to Avoid

The use of #define constants is strongly discouraged, using const is recommended instead.

The use of #define macros is strongly discouraged, using inline functions is recommended instead.

The use of typedef is strongly discouraged where actual types such as class, struct, or enum could be used instead.

The use of extern (e.g., global) variables is strongly discouraged. The exception is for programs which benefit from having a small number of object pointers accessible globally via extern. The use of goto statements is not allowed.

4.8 Macros

#define MAX( x, y )   ( (x) > (y) ) ? (x) : (y) )

4.9 Debug Compile-time Switch

#ifdef DEBUG
    cout << "MeaningfulName::doSomething: about to do something" << endl;
#endif

4.10 Memory Management

4.11 Constructors

4.12 Destructors

4.13 Argument Passing

void A::function( int notChanged );		  // default: pass by value

void B::function( const C& bigReadOnlyObject )    // pass by const reference

void C::function( int notChanged, int& result );  // pass by reference

4.14 Default Arguments

4.15 Overriding Virtual Functions

4.16 Const Member Functions

4.17 Referencing Non-C++ Functions

extern "C" {
    void aFunction();           // single non-C++ function prototype 
}

extern "C" {
#include "functions.h"          // library of non-C++ functions 
}

4.18 NULL Pointer

4.19 Enumerated Types

4.20 Terminating Stream Output

4.21 Object Instantiation

4.22 Encapsulation

4.23 Default Constructor