Code Style Guide

Jules Milner-Brage & Jeffery Walker

Naming:

ClassName
_ClassName // (private) supporting implementation for a (public) class
methodName(...)
_methodName(...) // (private) supporting implementation for a (public) method
StaticMethod(...)
accept(...) // the accept method of a visitor's context
whenCase(...) // a visitor's visit method
operator() or execute(...) // use to invoke a command as part of the command pattern
createSpecifier(...) // A method which factories an object the caller is responsable for deleteing. The specifier may be ommited and is used to quilify the kind of thing being created or the form of creation.
destroy() // Request an object delete itself. Assume the object has been deleted after invocation.
Instance() // a singleton's static accessor method
propertyName
CONSTANT_PROPERTY // prefer const over #define
staticProperty
instance // the singleton's static varible
module_name // multi-word module names should be avoided
Generics:¹
- τ // Tau: general type variable
- δ // Delta: as tau when typing data, esp. general collection type
- ρ // Rho: return type
- α // Alpha: argument type
- ε // Epsilon: exception type
Files (C++):
- module/ClassName.h// nested directories are used to reflect nested modules
- ClassName.c++
- module.h // to include an entire module
- module_part.h // to include part of a module
- system_level // for system level headers (e.g. garbage collection is gc)
- module /.test/test_ClassName.c++ // classes for doing unit tests go here

Do not use 'A' or 'I' as a prefix to an abstract class or interface. Proper names can imply when something is abstract. Also, interface does not always have meaning in a language. When using a pattern consider using the pattern name in the class in addition to a meaningful root name. A class' role in a pattern may also make a useful name part.

Header files will always have .h extensions and be in a directory reflecting their nesting in modules. System headers are for things considered so important that you directly use their name. In this case a header is generated without a .h and it includes the one with the .h. If multiple system headers would have the same name (i.e. vector) then including the name includes all classes with that name. Since they are in different modules no conflicts occur and using directives should be used to select the desired implementation.

Preprocessor:

#ifndef headerFileName_h_

#define headerFileName_h_




	// include directives

	

	// header file contents

	


#endif // headerFileName_h_

Comments:

Do not use c-style comments for one line comments
// BUGBUG JTW message marks code you believe may have an error or need fixed in the future. Includes author's initials in multi-author environment
There is a space between the slashes and the beginning of the comment message
Prefer no period/leading capital; at least consistent within a comment
Java Doc style comments are recommended especially when in a Java environment. Similar functionality is available in C++

Spacing:

Parentheses should not have spaces on either side of them
The scope resolution (::) and member selection (. or ->) operators should not have spaces on either side
Any comma or colon should not have a space before it but should have a space after it. The colon in the conditional operator is the only exception to this, it is a binary operator and has spaces on both sides
All other binary operators should have a space on both sides
Unary operators should not have a space between them and their operand but should have one on the other side
In type declarations the type modifiers * and & should be associated with the variable name. If they are return types the modifiers should be associated with the type
The one time when there is a space after a ')' is when declaring a const method or to separate it from an inline body
Curly braces when present should be on lines by themselves and should be at the surrounding indent level. If they are together on a line, as when inlining an empty or extremely short method body, there should be a space between them and anything else or each other (i.e. { } not {})
Class initializer lists should be written with the colon immediately after the declaration and each variable listed on its own line below, tabbed in one level
Templates in C++ should be on their own line before the templated item, at the same tab depth

class ClassName: public SuperName

{

private:

    static ClassName *instance;



public:

    ClassName()

    ClassName(int x): property(x) { }



    virtual void method1(Type &param, Type2 param2) = 0;

    virtual void method2(Type &param, Type2 param2);

};



ClassName::ClassName():

    property(8),

    foo(7)

{
}



void ClassName::method2(Type &param, Type2 param2)

{if()

{
}
}

Code:

Do not inline virtual methods
Always include a virtual destructor in super classes
Parentheses will not appear around arguments to return
Named inner classes should be at the top of the class
Code sections go private, protected, public
When templating, code should be in the header file with an empty C++ file that includes the header file
In C++ use the new style cast operators.
private: should always be used (don't go with the implicit private that starts a class)
List friend declarations before any access modifiers
Use for(;;) to mean forever rather than while(true)
Use of pointers vs. references:
- Use pointers if you need to:
  1. have a null pointer
  2. change which object is referenced
  3. delete an object (even when destroy() is used to delete)
  4. return an object the caller is responsible for deleting
- Use references if you need to:
  1. do anything not the above
  2. are returning a singleton or singular static instance (i.e. Null())
Standard Singleton Implementation:

Type* Type::instance = 0; Type& Type::Instance() { return *(instance ? instance : instance = new Type()); }

¹ may be used in a parameterized form <type variable>specialization (e.g. τVisitor).

jwalker@cs.oberlin.edu