File Structure

With rare exceptions, all files of the same type should have the same basic structure. This section describes the standard file structure:

Line Width
File Size
Indentation and Tabs
Source File Comment Block
Separating File Contents into Blocks
Header File Structure

Line Width

Use an 80 character line width for all files. Avoid extending lines more than 80 characters by breaking up code and comments across multiple lines. However, do not cut code and comments short -- extend them the full page width to avoid wasted space.

The following example shows a problematic comment:

	// This comment could fit on
	// one or two lines, but the developer
	// didn't clean it
	// up. As a result, it wastes space in
	// the file.

The line width rule is optional.

File Size

Files should not exceed 1000 to 2000 lines. Because it is difficult to find code in extremely large files, separate files larger than this into multiple files.

However, do not create inconvenient file breaks, such as breaking the member functions of a class into two files, just because the length exceeds the guideline. This increases the difficulty of understanding the code. If a class requires that much code, consider other object architectures that might logically reduce the size of the class.

Indentation and Tabs

Use indentation to align portions of the code and significantly improve readability. Most text editors support "indentation-width" or "shift-width" options. Use these options and set the default indent to four spaces. This sets all indentation levels to multiples of four and any alignment boundaries are on a multiple of four spaces. Always use spaces instead of tabs.

When coding a statement over multiple lines, align the second and subsequent lines to the first non-white-space character following an opening parentheses. If a statement uses no parentheses, align the second and subsequent lines by two shift-widths. For example:

    return memcmp(&params, &paramTbl[index], sizeof(oaViaParamData)) == 0
        && params.cutPatternSize == cutPatternTbl.getNumElements(index)
        && (params.cutPatternSize == 0
            || memcmp(params.cutPattern, cutPatternTbl.get(index),
            params.cutPatternSize) == 0));

Source File Comment Block

If you are creating a new source file that was not part of an OpenAccess distribution, replace YOUR_COMPANY_NAME with the name of your company.

//*****************************************************************************
//*****************************************************************************
// <fileName>
//
// Add a description of what this file contains. This comment should pertain
// to the entire contents of this file, not any particular portion.
// Comments of that type should be placed above the specific portion.
//
//*****************************************************************************
// This source file contains copyrighted material developed by YOUR_COMPANY_NAME.
//
// The rights to this source file, its machine readable form,
// and any representation of the material contained herein,
// are hereby transferred to and are owned by Si2, Inc.
//
// This material is copyrighted by and may not be reproduced
// in any form except under the terms of your OpenAccess license
// or with prior written permission of Si2, Inc.
//
//                  Copyright (c) 2007 Si2, Inc.
//                      All Rights Reserved
//*****************************************************************************
//*****************************************************************************

Separating File Contents into Blocks

Divide the contents of a file into easily understood, functionally unique blocks. Visually separate the blocks with three blank lines to make it easy to differentiate the material. Add a comment to each block. Types of functional blocks include:

Function or class member function
Class, structure, or enum definition
Static member assignments

The following example shows how to separate functional blocks.

// *****************************************************************************
// Initialize Static Members
// *****************************************************************************
const oaFloat           myClass::myStaticFloatVar       = 5.0f; 
const oaBoolean myClass::myStaticBooleanVar     	= TRUE; 
const oaMyClass *myClass::myStaticClassPtr              = NULL;



// *****************************************************************************
// myClass::myMemberFunc()
//
// This is the description of this function. It describes this function, what it
// does, and how it works.
// *****************************************************************************
myClass::myMemberFunc()
{
        <function contents>
}



// *****************************************************************************
// myClass::myOtherMemberFunc()
//
// This is the description of this function. It describes this function, what it
// does, and how it works.
// *****************************************************************************
myClass::myOtherMemberFunc()
{
        <function contents>
}

Separating the file into blocks is optional. Users can determine how much inter block spacing is required (if any).

Header File Structure

Enclose the entire contents of header files between the commands #if !defined(...) and #endif to protect against multiple inclusions. Every header file must end with #endif as the last line of the file.

For example:

	<FILE HEADER COMMENT BLOCK>

	#if !defined(<fileName>_P)
	#define <fileName>_P

	<FILE CONTENTS>

	#endif

Return to top of page