Advanced Rendering Toolkit
Coding Style

How to format your source code.

Since the programming language we use is Objective-C, we define a set of rules on how to format source code written in this language. Using a consistent style throughout the whole toolkit makes it easier to read code written by other programmers. This file gives a description of the style that is used for the ART libraries.

Basic rules

Source Code Language: The language of computer science is english. The keywords of Objective-C are also borrowed from english language. Therefore all expressions introduced by the programmer should be in english as well. This applies to all kinds of text a programmer might use in a source file: type names, variable names, function names, comments and explanations. If a programmer follows this guideline, his programs can be almost as readable as text written in plain english. An implication of this rule is, that abbreviations should only be used if they are generally accepted (i.e. the language of computer science is english not abbrev. eng.). There are exceptions, where abbreviations are quite adequate: for example it is acceptable to shorten the components of long compound-names (But this should be done uniformly, so that the same expression is always written either spelled out or abbreviated, but not both).

File formatting

General Rules

A file should have a maximal width of 78 characters to ensure it can be properly read and edited on every terminal.

File Header

Every source file should have a header consisting of comments that contain the following information:

`NAME:`	the name of the file without extension
`TYPE:`	c header, c code, objective-c header, objective-c code, yacc source, or whatever filetype it may be
`PROJECT:`	the name of the project this file is part of
`CONTENT:`	a one-line description of the purpose of this file
`AUTHORS:`	the names of the authors of this file (i.e. the people who created and modified this file)
`HISTORY:`	chronolgy of modification of a file wich minimally contains the creation date and the date of the last modification. The time of the change is optional, dates should always be written with letter-shortcuts of the months.
`MANUAL:`	for header files this together with specially formatted comments contains the complete interface documentation for the module; for other files this contains an optional description of the contents of the file.

Indentation

The standard indentation is four characters.

The indentation is generally four characters. All the lines that are part of the same block have the same indentation. Continuation lines are indented according to corresponding structural parts of the expression, or at least eight characters.

In case this is not possible the continuation line should be indented at least 8 characters in addition to the base indentation.

The opening and closing brace of a block are in the same row or column.

The opening and closing brace of a block has to be either

in the same column, or
in the same row.

The opening brace after a for, if, while or function head has to be directly under the first character of the statement, e.g.

	    for (i = 0; i < numberOfSubNodes; i++)
	    {
		...
	    }

or the whole block is in the same line, e.g.

	    if (currentMax > current) { currentMax = current; }

The opening brace of a function call or function definition should be directly after the function name without a space inbetween, e.g.

	    strcmp(charPtr,buffer);

The opening brace of the expression following one of the keywords if, while, for and return, should be offset from the keyword by one space, e.g:

	    while (--counter > 0)
	    {
		...
	    }

Name space

There are a number of possible naming schemes for different entities. We define the following names for these schemes:

lower mixed case: The name is written in lowercase, each new word is started with a capital letter. The first letter after a digit is in lowercase. For example: lowerMixedCase, local2world.
upper mixed case: Same as Lower Mixed Case except it starts with a capital letter. The first letter after a digit is in uppercase. For example: UpperMixedCase, Vec3D.
lower underscore: The name is written in lowercase, words are separated by underscores. For example: lower_underscore.
upper underscore: The name is written in uppercase, words are separated by underscores. For example: UPPER_UNDERSCORE.

Types

Names of classes, typedefs, and enums are written in upper mixed case.

For example:

	    InMassActor, SimpleWindow

Functions

Names of C-functions are written in lower underscore.

For example:

	    int roots_of_poly(		// calculate polynomial roots
		unsigned int n,		// order of the polynomial
		double * pol,		// coefficients x^0 ... x^n
		double * roots		// OUT: roots of the polynomial
		);			// OUT: number of roots

Methods

Names of Objective-C methods are written in lower mixed case.

For example:

	    - (void) transformPoint
		    : (const Pnt3D *) inPoint
		    : (Pnt3D *) outPoint
		    ;

Structure fields and C Variables

Names of structure fields and C variables are written in lower underscore.

Class Members and Objective-C Variables

Names of class members and Objective-C variables are written in lower mixed case.

Accessor Methods

Methods to get or set a data member of a class are called accessor methods. Names of accessor methods are written in lower mixed case and use the name of the accessed class member, prefixed by 'get' or 'set', or just the name of the accessed class member if the value is handed back using the 'return' statement. For example:

	    - (void) getImageSize
		    :(IVec2D *) outImageSize
	    {
		*outImageSize = imageSize;
	    }
	    
	    - (void) setImageSize
		    : (const IVec2D *) inImageSize
	    {
		imageSize = *inImageSize;
	    }

	    - (const char *) nodeName
	    {
		return nodeName;
	    }

Macros

Names of macros are written in upper underscore.

For example:

	    #define MATH_PI	3.14159265359
	    #define THIS_MUST_BE_A_MACRO(a,b,c)

Constants

Names of constants are written in upper underscore.

For example:

	    extern const Pnt3D G3D_P_ZERO;

Enumeration values

The values of an enumeration type are written in lower underscore.

For example:

	    typedef enum ArsHitState
	    {
		arshit_nothing_valid		= 0x0,
		arshit_valid_local_point	= 0x1,
		arshit_valid_local_normal	= 0x2,
		arshit_valid_world_normal	= 0x4
	    }
	    ArsHitState;

Documentation

General Rules: Each file should contain the complete documentation which is necessary to understand its contents. This prevents the loss of the documentation, since it is a part of the files that are used for implementation.
Header Documentation: Objective-C header files define the interface of a module. Therefore they have to contain the complete documentation of the interface. If this documentation conforms to certain guidelines a tool can be used to automatically generate a man pages, html documentation or other types of reference material from header files.
Implementation Documentation: All documentation on the implementation of algorithms should be placed as close as possible to the actual implementation. This can be done by placing comments along the code and putting more general information, like references to algorithms and further documentation at the top of the implementing function or at the top of the implementing file.

Implementation issues

Floating point values: Always use the build-in type double for floating point values. It is not that much slower than float and will help you getting numerically more meaningful results.
Messaging nil: Objective-C defines that messaging nil objects is not an error, and just results in a no-op. Due to the way this is implemented this works fine, even when a value is returned. Thus checks for messaging nil are mostly omitted. Be however aware, that if you initialize a value from the return value of a method, and then you invoke the method on the nil object, the result is undefined!

ART / Documentation / Coding Style

This page is maintained by Robert F Tobler. It was last updated on August 27, 1999.
If you have any comments, please send a message to rft@cg.tuwien.ac.at.

Advanced Rendering Toolkit Coding Style

Basic rules

Source Code Language

File formatting

General Rules

File Header

Indentation

Name space

Types

Functions

Methods

Structure fields and C Variables

Class Members and Objective-C Variables

Accessor Methods

Macros

Constants

Enumeration values

Documentation

General Rules

Header Documentation

Implementation Documentation

Implementation issues

Floating point values

Messaging nil

Advanced Rendering Toolkit
Coding Style