Coding Guidelines

Introduction

This is the preliminary EnergyPlus C++ coding guidelines. It is likely that this will evolve and grow considerably over time.

These guidelines will gradually become enforced by both code scanning tools and code reviewers.

Source Files

• Header file names have a .hh extension
• Source file names have a .cc extension
• Header and source files (we call these both "source" files in some contexts) have Linux-style (\n) line terminators (dos2unix can convert to this)

Source Structure

General

• No trailing spaces are allowed: Most good editors/IDEs can be set to trim off trailing spaces on Save and stand-alone tools can do this

Indentation

• Tab indentation is used

Line Wrapping

• Line wrapping is discouraged for now: Most editors/IDEs can do soft wrapping in the display
• Line wrapping that is permitted should wrap at the same indentation as the initial line but with a single extra indent space
  • emacs style wrapping (aligning wrapped lines at the open parenthesis of a function is not allowed
• Function arguments that are wrapped on separate lines should get an extra tab indent
• Functions with more than a few arguments should be wrapped to one argument per line
• Functions with one argument should not wrap the argument to a separate line unless an argument comment is needed or it is part of a family of functions that have wrapped multiple arguments

Header Files

• Header files have include guards wrapping the whole file of the form

#ifndef NamespaceName_FileName_hh_INCLUDED
#define NamespaceName_FileName_hh_INCLUDED
...
#endif

## Includes

* Includes must be complete and minimal:
  * Headers should include everything they need so that they can be compiled if included alone in a .cc file
  * Headers should not include anything they don't need: "weaker" forward declarations or forward declaration headers should be used instead of full headers wherever they suffice
* When you modify a file you are responsible for checking for any obsolete, duplicate, or too-strong headers
* Includes should be grouped into sections in this order and with these comments:
```cpp
// C++ Headers
...
// Some_Package Headers
...
// ObjexxFCL Headers
...
// EnergyPlus Headers
...

• A .cc file should include its own header file first in the EnergyPlus Headers section
• A .hh file should include any base header(s) first in the EnergyPlus Headers section
• Other headers should be in alphabetical order in each section

Namespaces

• namespaces are normally given lowercase names
• No extra indentation in namespaces
• namespaces are marked like this:

namespace thing1 {
namespace thing2 {
...
} // thing2
} // thing1