This table details the proper form for symbols representing classes, methods (functions), and fields (variables). We avoid the used of "_", this takes more characters, is harder to type, and is not typical of most developers. Also, leading underbars can be confused with some automatically generated internall compiler symbols.

Acronyms should stay completely capitalized if they are embedded in a name. Underbars may be used to divide pairs of acronyms when they occur adjacent to each other. It is better to pick a different name though, instead of using underbars and acronyms.

Examples:

• CIAAgent
• CIA_FBILiason

All names should be understandable English, and meaningful. The name should serve as documentation for a reader rather than a mnemonic shorthand for the writer. For example: loopCounter is preferable to lpCtr.

An exception would be to user shorter names for heavily used iteration or access variables. For example a loop performing extensive indexing might use a variable named "i", instead of "loopIndex". 0013 Naming,Classes Recommended OO, Java C++ Use specific names for classes, avoid generic words

Avoid class names which use common words like Object that have a high probability of clashing with other libraries. Also, make the names as specific to the context as possible (Coordinate is more specific than Number).

Names of methods (C++ functions) containing verbs should also contain the object of the verb ("object" in a grammatical sense) and should be in the form "verbObject," for example getSignature instead of signatureGet.

Verbs from the following list should be used to form function names when applicable:

• getObject
• setObject
• compareObject
• computeObject
• performObject
• processObject
• testObject

In some cases, a class is composed of small, heavily accessed components. The accessor functions for these components may eliminate the "set" and "get" prefixes if appropriate. For example, a class representing a 2-dimensional point might see these accessors in use:

point.x(3);              // Set the X coordinate to 3.
point.x(4 + point.x());  // Shift in the X direction by 4.
      

Methods (C++ functions) that create new instances of a class should be prefixed with 'create'.

Files are named to match their associated classes exactly, with the same capitalization. If more than one implementation file is needed, they are distinguished by suffixes. If the operating system imposes a file name length limit, select a meaningful abbreviation. More arcane operating systems may not be able to comply. We hope the last of these systems pass into history rapidly.

To obtain declarations for external variables, files must include the relevant information rather than having literal extern statements.

Friend functions should be used only for non-member binary operator functions and in special efficiency cases. The whole friend concept violates encapsulation and information hiding. Only classes which are very tightly coupled should be friends. One example of such tight coupling is a collection class and its iterator.

Global variables should be avoided at all costs. Use class scoped static data members instead. If you are forced to use one, a g prefix is suggested to make the variable standout like a sore thumb. For example:

        int gProcessNumber;
        char gFileName;
      

Be sure to comment all global variables and give them an initial value as well.

Many coding standards suggest a set of naming prefixes the help determine the scope or purpose of variables. This is not generally used and it may be hard to enforce across a large code base. However in certain well controlled bodies of code, it is possible to use this technique effectively. The following table demonstrates a set of prefixes:

If a header file is widely included, for example in as a library, it should not contain "using namespace" statements since these namespaces would then be forced on dependent classes. However, in the body files, the namespace statements can be used as needed for clarity and convenience. [cxxcs, rule 59]

Keep the packages/namespaces from being cluttered by restricting names to class scope where possible. If a class X is only used by a single other class A, nest the class X inside A. Enums can be similarly scoped.

Define packages (Java) or namespaces (C++) to prevent class name collisions. If packages or namespaces are not available, then use a one or more letter prefix for class names, starting the prefix with an upper case letter to observe the convention for class naming. For example, a project named IMAX could use Ix for all it's classes. A subsystem named AIMS might use Am. Some examples:

IxImage
AmFile

Make all class members private to maintain the object-oriented design technique data hiding, and to keep users of classes independent of their implementation.

Exception: Use protected keyword to provide direct member access for derived subclasses, whether the subclasses are created at the same time or in the future. This is more complex class design issues that requires attention to the future evolution of the inheritance hierachy.

Exception: Use public in very restricted circumstances where a class is expected to never change it's implementation, and the access is so heavily used that the method call overhead is a problem. For example, a Coordinate class might have public members for it's x,y, and z values. Use this with caution!

Default function arguments values should be specified with the function declarations in the header files and not with the implementations in the body files.

Accessor functions should not modify the object and are declared as const as well as returning an object (copied on the stack), a reference to a const object, or a pointer to a const object. This prevents unexpected side effects from occuring later in the the control flow.

Functions with the ellipses argument should be avoided except in rare cases. If required, use the <stdargs.h> implementation instead of the older <varargs.h> one.

Members in an initialization list should be in the same order as their declaration inside the class.

Avoid using assignments to initialize class members; use the constructor initializer list instead. The use of these initialization techniques is expected by C++ programmers, and is also the only way to initialize reference and const members. Place the initializer list under the class name. For example:

void
Thing::func(int i, long l) : member1(i), member2(l)
{
  ...
}
      

All destructors should be defined as virtual. This handles the situation where a pointer to a base class is used by delete to deallocate an object, and it is vital for the virtual behavior to allow the most derived class to free its data members through its own destructor first.

Exceptions would be real-time or embedded applications where the virtual table traversal may not be justified in space or time impact.

In the assignment operator all data members and base classes should be assigned values to bring the object a known state.

The assignment operator must test for assignment to itself as its first act. If this case is executed, the left hand object may be destroyed (as many assignment operators do) before it can be assigned values from the right hand object.

The return type of the assignment operator should be a const reference to the class and should return *this:

const Thing&
operator=(const Thing& thing)
{
  if(thing == this) return(*this);
  else
  {
    ...
    return(*this);
  }
}
      

Member variable initialization when performed in the declaration statement is performed in constructor format. For example:

typedef UINT4 Time;
Time t(0);          // Correct.
Time t = 0;         // Incorrect.
      

Lengthy function argument lists should be divided across several lines, giving the opportunity to comment each argument on each line. Also, the first argument begins on a new line so that the length of the function name does not affect the indentation of the arguments making them easier to spot. Also note the aligned indents for the one line comments. An example:

int
manyArgumentMethod(
  char c,     // A single character.
  Time time,  // The time in seconds.
  Date date); // The Gregorian date.
      

Reference or pointer parameters which are not modified by a member function should be declared as const, allowing the compiler to enforce the designer's intentions. Passing parameters as a const reference can be more efficient than passing them by value, since only a pointer is placed on the call stack, instead of a copy of the value. So, for example, if a pointer (4 bytes) is shorter than a copy of an entire class (many bytes) the call stack loading and unloading will be faster.

Member functions which do not change an object's logical state should be declared const while the implementation casts away the const internally. This protects the caller from performing a dangerous cast that only the class implementer should address. This also allows the compiler to enforce the designer's intentions.

Regarding canonical methods (constructors, copy constructors, destructors) please do at least one of the following:

• Implement and test each method
• Make the method private so a compile time check will be made
• Put a special error handler into the method so at execution time, anyone calling it will be notified.

We do not want each compiler making arbitrary decisions about where each method is implemented.

To aid readability, order the class implementation into these sections:

• public section including:
  • constructors
  • destructors
  • methods
  • members
• protected section including:
  • methods
  • members
• private section including:
  • methods
  • members

In general, member functions (except the constructors and assignment operators) should be declared virtual to allow derived classes to express virtual behavior. If a member function must explicitly avoid virtual behavior, then leave out the virtual keyword.

Do not use C-style comments to 'comment-out' sections of code. If other C comments are encountered some compilers may not nest the comments properly. In C++, use the preprocessor directives like #ifdef ENABLE_THIS / #endif instead. In Java, us a simple if(false) { ... } instead.

When comment lines are associated with statements, the indent depth is matched (Java code is shown):

// The main loop.
//
int fact = 1;
int fib = 0;
for(int i=1; i<=4; i++)
{
  // Perform the calculations.
  fact *= i;
  fib += i;

  // Display our progress.
  Susyem.out.println("Factorial so far is "+fact);
  System.out.println("Fibonacci so far is "+fib);
}
    

If a short single line comment applies to one or more statements, it can be placed after the statement on the same line preceded by the usual "// " introduction.

If multiple statements are near each other with trailing comments, try to align the comments vertically. If a few statements are exceptionally long, don't let them force all the other comments out. For example:

int   i;          // Iteration variable.
Image inputData;  // The input image.
char  string;     // A temporary buffer.
Image imageWithManyPixels;  // The big image.
int   depth;      // The water depth.
      

In Java, each public class is implemented in a single file This is enforced by the compiler. Inner and private classes can be placed into the same file.

In C++, Each class has two files: one header file and one or more implementation files. The header file should define one class only, or a small group of very tightly coupled classes. It should also be named to match the class name exactly.

For Java the source files are suffixed with ".java". This is the only choice, and is enforced by the compiler.

For Java, long ago Sun established the suffix java and it is now written in stone. The shorter j would have been welcome but probably conflicted with some other preexisting system.

For C++, the file name suffixes are .hh for header files and .cc for implementation files. The lower case doubled letters distinguish these file from C source files, and are the easiest to type (no shifting, and a repeated single character us very fast to type). These are less desirable, but often seen alternatives:

For scripts, an official script suffix is best. The inconvenience of the extra suffix when executing scripts can be addressed by creating a symbolic link (on UNIX), or a "shortcut" (on Windows) with the shortened name if desired. The suffixes have proven to be useful for development tools as well as certain operating system file classification systems which need this extra information when processing or analyzing files.

• sh - bourne shell
• csh - cshell
• ksh - kshell
• pl - perl
• m - matlab
• py - python

Each line in the file should be less than or equal to 78 characters long to avoid problems with printing and various screen editors.

If a language statement must be broken across a line, break the statement just before an operator, and start the next line indented, with the operator at the front. This reinforces the fact that the start of the second line is a continuation of the previous line.

Each file also has specific requirements for commenting content. All files need to have the starting comments similar to these:

// Example.java
// Copyright 2001-2003 YoyoDyne, all rights reserved.
    

If you are using the CVS or related version control systems you can use the special tags that are automatically substituted instead. Refer to the example subdirectory.

Any extra header information beyond the copyright is less important now that Javadoc and Doxygen solutions are available. See the other rules for class and method documentation for details.

It is not a good practice in import statements to use the "*" wildcard character to allow access to an entire level of the package hierarchy. Instead, it's more useful to call out individual classes with separate import statements. This makes it easier to determine the dependencies between java source files.

The exception to this rule is the use of standard Java packages in which a large number of the classes are in use, and the number of import statements would be prohibitive.

Mark spots in the code which require future attention in comments with the special sequence XXX:. This can be used as a search field to locate problem areas. This is in keeping with common practice for open source development (Linux, FreeBSD, etc).

It is also an advantage to append include your own initials if resolution of the issue should be referred to you.

Examples:

• /* XXX:RLV: The next version should use a bubble sort here. */
• /* XXX: This method needs to switch from HashTable to HashMap. */

Implementation files must never include other implementation files. Although the compilers will support this, it is unexpected and can confuse developers working on the program.

Header files only include header files for classes used in that classes declaration, otherwise, forward declarations are used instead. This speeds compilations. Forward declarations merely identify the particular name as a class:

class Foo;

class Bar
{
   Bar(Foo* x);
}
      

Variables should be declared in the smallest enclosing scope possible. This makes it easier to locate their declarations.

All variables should be separately declared, one variable per line. This promotes proper commenting of each variable. In some cases a group of variables are tightly coupled and can exist on one line: (e.g. x,y,z).

Doxygen supports both an "at" sign prefix and a backslash prefix. Use only the "at"sign prefix to maintain compatibility with Javadoc. The backslash form can only be used if you can guarantee your source code won't be reused by another project that might want to use a more common tool like Javadoc.

Each file (header file in C++) should declare only one class. Mixing multiple classes into single header files makes it difficult to locate the code for any given class. In Java, nested classes are allowed for this purpose, but should be used carefully.

Each header file has the following basic order of contents:

• Preprocessor tests for inclusion.
• File Comment block
• Preprocessor protected include statements
• Forward declarations
• File local typedefs
• Extern and constant declarations
• Struct, union, and class definition blocks
• Inline function definitions

The very first and the last lines of each header file contain special preprocessor lines to prevent multiple processing of the same header file during compilation. A unique symbol is defined which can be tested by the compiler. At the top of each header file:

#ifndef EXAMPLE_HH
#define EXAMPLE_HH
    

At the very end of each header file there's a companion line:

#endif
    

Then in each effort to include the designated include file, Any #include statements are each individually wrapped as follows to improve compiler efficiency. This allows the compiler to avoid even opening any additional files unless the files have not yet been seen. See a later rule which shows how the tested symbol is defined. In code control systems like ClearCASE (tm), the speed improvements can be dramatic. An example follows:

#ifndef EXAMPLE_HH
#include "Example.hh"
#endif
      

Each class definition will be preceded by a comment block to describe the class. See the example subdirectory.

The specialized tags shown work in several documentation generating systems including Javadoc, and Doxygen.

Within the class declaration, each member function or attribute is preceded by a comment block which has a very specific format. This is the prime location for general information used by people calling the class methods. In C++ the header file should be preferred over the body file as the body file is not always distributed. See the example subdirectory. This format is compatible across javadoc and Doxygen.

Optional: Also note that the example's the method name is placed on it's own line, left justified to make it easier to scan visually down through a class for a particular method by name. If the usual technique of putting the keywords and method name on one lines are used, the method name ends up at an unpredictable depth making it difficult to spot.

Methods can be broken into groups by using a horizontal lines in comments and a title. For example:

  //
  //---- Method Group 1 ---------------------------------
  //

  ...

  //
  //---- Method Group 2  ---------------------------
  //
    

Unfortunately Javadoc does not support this formally, as it alphabetizes all the methods instead. This is an interesting tradeoff, but the organization of the source code this way can still be valuable. Doxygen does support this through specialized tags, but unfortunately, this would be lost in Javadoc processing.

Const should be used as the default designation for function arguments, unless the function needs to return information through the arguments in question. Many believe that const should be the the language default and a new keyword like volatile would be available for non-const needs. The following C++ example function shows a const in every possible location:

  const Point& convert(const Point& point) const;
        

In-line member functions have special needs. For each function, put a conventional declaration inside the class declaration block with it's associated preceding comment block describing it's use. After all, inline functions are used in exactly the same manner as regular functions. After the end of the class declaration block place the complete implementations for all the in-line member functions. For example:

  /**
   * An inline function of note.
   */
  inline void
  Example::func()
  {
    ...
  }

  /**
   * Yet another inline function of note.
   */
  inline void
  Example::func2()
  {
    ...
  }
      

Constructors, destructors, and virtual methods must not be declared inline. The address of these methods may be preserved, possibly implicitly, and would result in multiple copies of the code being created.

Only accessor, mutator, and very short functions can be declared inline. Code bloat can be severe otherwise.

I/O (via iostream.h) should not be performed within inline functions, otherwise code bloat via the include of iostream.h can occur.

All system-wide typedefs are collected in a shared header file. If the system is divided into reusable subsystems, then each sub-system has it's own shared header file with typedefs.

Enumerations should be declared within a relevant class to obtain qualified name scoping. The enum itself should be named with the same conventions as a class (capitalized). The enum members are similar to symbolic constants and should be each all upper case. Also, its very useful to define an explicit illegal value for error checking. Enums values can order themselves automatically, so the illegal value is forced to -1 at the end of the list, allowing automatic numbering for the regular values. Here is an example:

class Display
{
  enum Color { RED, GREEN, BLUE, ILLEGAL=-1};
};
      

color = Display::RED;
      

Lengthy derivation lists should be divided across lines. In Java:

class SubClass extends
  SuperClass1, SuperClass2, SuperClass3, ...
      

Member access identifiers in class declarations should be ordered public, protected, then private, with the private identifier explicitly specified; it is the default if no designator is present can be confusing if absent.

In the class declaration, member functions are declared first, followed by data members.

Each implementation file has the following components:

• File header comments including the file name and copyright information.
• Include directives, with at least the header file for the current class
• Global data initialization
• Static data initialization
• Static data function declarations
• Friend function and binary operator declarations
• Member function definitions
• Static function definitions

Each function is preceded by a comment block with a description of its detailed implementation as needed. This information is an extension to the short information provided in the header file for each function. The user of this class should only need to read the header file comments and declarations to effectively use this function and only consult the implementation file when studying the implementation is warranted.

Try to keep method implementations less than 100 lines in length. Methods that are shorter are easier to comprehend and maintain. Shorter methods also support a modular approach where complex operations are subdivided into simpler operations.

In the definition of methods, references to class data members should not use the historical this pointer, since the language supplies it implicitly. Since the most common activity in methods is the manipulation of member data, this assumption is justified. Some style guides recommend the use of a special prefix for all data members; although this is better than using the this pointer, it still is not justified as above. However, many projects and libraries have started using special prefixes like "my" for class data members so if it can be consistently applied across a related set of classes, then this is reasonable.

Parenthesize complex expressions if operator priority is in doubt. For example:

result = (one + two) * three;
      

Instead of "casts" for explicit type conversion, apply a function style conversion with the name of the required data type to the variable or value:

int i(4);
float x = float(i);
      

Use compound assignment operators whenever possible, as they are natural to Java, C++, and C. They aid rapid comprehension of the operation. For example, use:

result += 2;
      

result = result + 2;
      

If a compound assignment operator += or -=only requires changing the value by one, use the monadic increment or decrement operators:

result++;
++result;
      

Initialize pointers when they are defined. If no value is ready, initialize them to 0. For example:

int two(2);
int* twoPtr(&two);     // twoPtr is a pointer to an int
      

Test for 0 pointers explicitly when possible:

if(pointerVar == 0) cout << "Economic Module: Oops!" << endl;
else pointerVar->computeGrossNationalProduct();
      

Use initialization instead of assignment for efficiency. Thus a declaration followed by an assignment requires calls to the constructor and the assignment operator, whereas initialization will simply call the constructor.

All indentation is performed with space characters instead of tabs. Tabs can confuse printers and editors. Many text editors can be adjusted to map the tab key to the correct number of spaces automatically.

All indentation is done with two spaces per indent level. Two spaces is optimal for supporting deeply nested code and is more convenient than typing three or more spaces to achieve each indent level. If small changes are in progress on a file with a different indentation scheme, conform to the existing scheme. Each file should exhibit only one scheme.

The curly braces mark code blocks and are lined up with the statement with which they are associated. The statements within the block are indented within those braces. This provides a reasonable visual form for the block. One can quickly scan for the block starts and ends and it easier to perceive nested cases. The old Kernigan&Ritchie technique of "hiding" an open brace at the end of a line tends to obscure this visual form, and makes the visualization of the code structure more difficult. An example with one level of code block nesting, notice how your eye can pick out the nesting immediately:

if(value == true)
{
  System.out.println("The value is true");
  if(value2 == true)
  {
    System.out.println("The other value is true too.");
  }
}
    

If a code block ({}) is exceptionally long, put an in-line comment after the closing brace to correlate with the conditional that may be present at the start of the block, otherwise select a unique phrase.

if(value == true)
{
  ...many, many lines....
}  // if(value == true)
      

If a conditional statement has a short executable result, then it may be placed after the test without the braces as follows:

if(value == YABBA) Yabba();
if(value == DABBA) Dabba();
if(value == DOO) Doo();
      

A single statement which is the result of a conditional test should not be placed on it's own line without braces to surround it. Without the braces the statement relies on indentation as the sole means to define the code structure which is risky, and can lead to errors and difficult to find bugs.

Correct:

if(value == true)
{
  System.out.println("The value is true.");
}
if(otherValue == true)
{
  System.out.println("The otherValue is true.");
}
    

Incorrect:

if(value == true)
  System.out.println("The value is true.");
if(otherValue == true)
  System.out.println("The otherValue is true.");
    

The down side, for blocks with only one statement, is that the code uses extra vertical space (2 extra lines). With caution, one can break this recommended rule, realizing the danger to the proper perception of program structure, that is then only clearly indicated by indentation. The tradeoff between conciseness and easily perceived structure is at issue here. We recommend structural clarity over conciseness.

Declarations of variables should not be used in the initializer section of for statements if the variables value will be used after the for loop exits. The newer language specifications are changing the scope of initializer section variables limiting them to the for statement and the enclosed block only. Instead, it is best to place them just before the for statement.

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

All Class and structure declarations should have a name and should not also be used to declare instances. Below shows the proper separation of a structure and its instances.

struct Coord
{
  int x,  // X Coordinate.
  int y   // Y coordinate.
};
struct Coord c1,c2;
      

A functions should have explicitly stated return types. This includes the function main() that should now return int as the old exit() function can now be replaced by a return(). In older C compilers, functions which had no defined return types defaulted to int and supported a bad habit of underspecified function declarations.

The return type of all method declarations and definitions should be placed on a separate line before the method name allowing the method name to be left justified and easier to spot in the code. Example of a method declaration:

/**
 * The locate method
 */
int
locate(int i);
      

The names used for the arguments to functions should be provided in all cases. In C++ that dummy argument name should be the same for the declaration and definition. The name should be selected to help indicate the use of that particular argument:

long
power(long base, long exp);
    

Avoid writing functions which return non-const pointers or references to their member data. This undermines encapsulation and information hiding, making the caller dependent on the internal operations of the classes.

Under no circumstances should you ever cast away a const on a return value. The const expresses a contract that the caller is being given access to a potentially private component which must not be modified. This is used on rare occasions for efficiency reasons to prevent an extra copy operation. However one should generally return copies of the data element if the size is not prohibitive.

C++ Example:

class Foo
{
  private:
    int x;
  public:
    const int& getX() { return x; }
}
    

main()
{
  ...
  Foo* f = new Foo();
  int& myX = (int*)f->getX();  // Error: cast away the const!
  myX++;                       // Consequence: Modified private data member of Foo!
}
    

If a function returns a non-const pointer to an object, the ownership is passed to the caller who becomes responsible for deletion and management of the object. In all other cases, the caller is not the owner of the returned object.

Pointers must be set to 0 unless they point to additional constructed objects. The older NULL practice should be replaced with a typeless 0, to prevent newer compilers from choking on NULL being set to (void*)0.

Destructors can be invoked on pointers which are either valid or 0. For most compilers the delete call will properly handle a 0 argument. If your compiler does not, or you need to support multiple compilers, consider using a macro named DELETE_SAFE as shown below:

#define DELETE_SAFE (p) { if(p) delete (p); }
    

The arguments to function should be a reference to an object instead of the object itself when appropriate. Passing without the reference designation will cause a copy of the object to be created on the stack which can waste time and space of the object is large. There are special cases when the argument needs to be copied in case it might be changes by complex control flows.

When passing arguments for input only also consider the use of the const keyword for those arguments.

Functions must not store pointers to arguments passed by reference. This is called the Linton Convention.

Unless otherwise documented, if a function argument is passed by non-const pointer the ownership should be assumed to be passed to the function, which then becomes responsible for the deletion and management of the object if so documented. All other cases leave the function's caller as the object owner. If the documentation does not indicate the assumption of ownership, the Linton Convention applies, and the caller must exercise care since the function might maintain an internal copy of the pointer which can become invalid after the call.

Exceptions: this rule does not apply to cases where the caller is expecting a function to have the side effect of modifying the object passed by pointer. Another case is where the caller allocates a fresh object and then passes it in to be filled. In these kinds of cases, the documentation must clearly indicate these specialized behaviors.

Each block of code which allocates new objects must delete them or pass ownership during their control flow. A memory leak will occur otherwise.

Data members should not be marked as public or protected. This exposes the class implementation and violates encapsulation and information hiding. Inline functions should provide ways to modify or access an object's state instead; this also maintains efficiency.

All classes which allocate their own additional objects on the heap (not the stack) or consume other shared resources must have definitions which support, as a minimum, the following member functions, making up a canonical class:

class Thing
{
public:
  Thing();                  // Default constructor
  Thing(const Thing&);  // Copy constructor
  virtual ~Thing();         // Destructor
  Thing&
  operator=(const Thing&);  // Assignment operator
protected:
private:
}
      

All constructors must initialize all their data members. Unknown and unpredictable value can creep around can hide serious bugs.

Use new and delete instead of malloc() and free(), and never mix both in a program. The newer constructs are easier to understand, and easier to overload.

Exception: if you are calling an older function (like something in libC) that may return "malloc"'d memory, they you should use free for that memory.

When an array is allocated with new directly, use the array form of delete. Some older compilers require this, but it also improves understanding.

int array[] = new int[20];
...
delete[] array;
      

The delayed nature of garbage collection makes the finalize method only appropriate for the release of resources local to the instance of the class. External resources, and methods on other classes that might block can cause JVM lockups. Manage these resources explicitly instead, outside of the finalize method.

Rewritten from original material in JOOP, v11 n 1, Mar/Apr 1998.

Static objects from other files should not be used in functions called at static constructor time. The order of inter-file static construction is undefined by the C++ standards.

A class should not depend on the internal structure of another class. This is often called the "Law of Demeter".

Stated more formally: In each method M of class C, only call methods of the following classes:

• Classes of C's members
• Classes of the arguments of M

Where possible use existing class packages (libraries) rather than implementing them. This can save time spent debugging classes which may never be as robust as public or commercial class libraries.

Class inheritance declarations must specifically indicate the protection, since private is the default and is counter-intuitive. If private is desired, the following example shows the correct form:

class Derived : private Base { ... };
      

A non-static method defined in a super class as non-virtual should not be overridden, as the super classes' function will be hidden. If the method must be static, it cannot be virtual and special care must be given to call up to the super class to preserve the inherited behavior if that is appropriate to the method's intent.

Provide and use implicit conversions sparingly. For example the following conversion from a C string to a String class instance is reasonable to provide and use:

class String
{
public:
  String(const char* = "");
};
...
void printOut(const String&);
...
printOut("Testing");  // Uses implicit conversion.
      

Avoid type casts unless absolutely necessary. They undermine the type safety offered by C++.

Inheritance hierarchies more than 3 levels deep should be watched, as the complexity may be too high.

Wide class hierarchies with more than 3 children from a base class should be watched, and more commonality may be captured with inheritance or templates.

Classes with less than 3 methods are usually candidates for elimination by merging with other classes. Classes are expensive to maintain and should justify their presence.

Classes with too many member functions are candidates for splitting into separate classes.

Minimize class coupling to make classes resistant to changes in the system at large. This aids reusability.

ToDo: an example is needed.

Use templates instead of inheritance when a family of classes only differ through member function argument and data member types.

Only use inheritance to express an "is a" relationship. Not for "has a".

Use multiple inheritance sparingly. It can often introduce potential ambiguities and complexity into programs, and these issues should be well understood before proceeding. Often the capability of multiple inheritance can be implemented with single inheritance and enlightened containment (inheritance by delegation).

Using an abstract class to embody pure design, i.e. nothing but abstract methods, is better accomplished in Java by using an interface. Whenever, a design calls for an abstraction that includes instance/state and/or a partial implementation, however, an abstract class is the correct choice.

From Teach Yourself Java in 21 Days by Laura Lemay and Charles Perkins.

All unary operators should be defined as member functions. This will suppress implicit conversions of the argument.

The functions operator=, operator[], operator(), and operator-> must be member functions based on the C++ language definition. These cannot be non-member functions.

Compound assignment operators (+=, -=, *=, /=, ^=, &=, |=, ~=, %=, >>=, <<=) should be defined as member functions to suppress implicit conversions.

All other binary operator functions should be defined as non-member friend functions so that both arguments are subject to the same access to implicit conversions.

Overloaded operator functions should mimic the built-in C++ operators, rather than inventing new operator concepts. For example operator+ should be used for adding, concatenating, etc, but not for more complex operations.

Reserve overloading for functions that perform the same activity from unrelated arguments (except for constructors). Flagrant use of overloading leads to confusing class designs.

If an operator has a complement, that complementary operator should be defined in terms of the original operator. This prevents the implementations from drifting apart. For example:

int
operator==(const Foo& left, const Foo& right)
{
  ...
}

int
operator!=(const Foo& left, const Foo& right)
{
  return( !(left == right));
}
      

All arguments and the final result of a macro expansion string are surrounded by sets of parentheses to prevent complex expressions from interacting during expansion. Expressions can be placed into the arguments or the whole macro may be part of a complex expression.

#define ADD(x,y) ((x)+(y))
      

No preprocessor commands which redefine or replace common language elements are allowed. This confuses C++ programmers reading the code, subverting their experience in recognizing the code structure. For example, do not use techniques like these:

#define then
#define begin {
#define end }

if (x == 1) then
begin
  cout << "X is 1." << endl;
end
      

Do not use "//" style comments in the definition of a multi-line macro. Since a macro definition can be composed of only one line (a clue that complex macros are a bad idea) all text after the first "//" will be considered a comment. For example:

#define MY_MACRO(arg) arg+one+two+three+four+ \
// Now let's add five and six \
five+six;
      

The following typedefs and #defines should be implemented or inherited from supporting header files:

typedef int bool;
#define true 1  // As assumed by ANSI C++.
#define false 0 // As assumed by ANSI C++.
#define null 0  // 0, a typeless 0, to allow the compiler to convert it.
                // This prevents older code which uses NULL to properly
                // use a typeless 0 instead.
       

const and enum should replace the use of #define for manifest constants. This allows more additional type safety, and also is more efficient since it is evaluated at compile time (called "constant folding").

Inline functions and templates should replace the use of macros.

Each subsystem has a base exception, from which each class derived it's own base exception, which can then have sub exceptions as required for the methods of that class.

The implementor of the subsystem decides how far down to supply detail.

This allows the caller to deal with the exceptions at any of three levels as provided: complete details for all exceptions, details only on which class (one base exception for each class), or no details at all, for the entire subsystem.

If a package is meant as a reusable component for building larger systems, it should almost never stop the execution of the overall system. In Java this means no calls to System.exit(). In C++ and C this means no calls to exit(). By keeping the execution alive, other parts of the system may be able to continue execution and prevent data loss if the error is properly signaled. Consider the use of Exceptions instead (except C).

Many modern applications employ multithreading to allow a single body of code to execute in several sections simultaneously. However, when these sections try to call each other, blocking can become a problem.

Whenever one thread of control invokes another section of the system (called a "handler" here), especially over a network, it is best for the handler to return the thread of control as rapidly as possible to the caller. One way to achieve this is to make note of the message inside the handler, and then return immediately, allowing another thread belonging to the handler to work off the request. If the handler blocks, it puts the caller at risk while it is blocked.

When any date is represented, in running code or when stored in any persistent or transient storage (everywhere folks!), the date must be represented with at least 4 digits as a text string, or an integer of at least 16 bits as an internal number.

Problems arise when computations compare pairs of dates that straddle January 1st, 2000 (2000-01-01). Although many clever schemes exist for making specialized assumptions and continuing to use 2 digit dates (for text strings) or 8-bit integers, these are perilous. Be advised that the trouble can occur any time the dates straddle 2000-01-01. So these have been occurring for years, and will continue to occur in the future for software that is incorrectly implemented with insufficient precision in the year representation.

Please overlook the storage size implications, as the reduction of latent bugs in the code is worth the impact.