SORTIE-ND
Software for spatially-explicit simulation of forest dynamics

Variable naming conventions

With SORTIE being rewritten according to the new framework, we have the opportunity to make the code more readable and consistent. The goal of the code standards is to make the code as easy as possible to read and maintain. Anything not explicitly covered in this document should be done according to that.

Code modules

Code modules should be organized with readability in mind. In general, functions should be shorter and more numerous.

Documentation

All code should be documented so that it can be understood by someone with basic programming knowledge. This means that something like memory allocation doesn't need documentation, but more obscure tricks such as bitwise shifts should be noted and explained if at all complicated.

Class documentation should be contained in the header file. Each member function should have complete information about how to use it, including what each argument is. This applies to both public and private functions. Each member variable should have a full description associated with it, which can just be a comment off to the side. We use Doxygen to automatically generate documentation from header files; all header comments should follow the JavaDoc style.

Functions which are not a member of a class (and there shouldn't be many of these, I think) should be fully documented with a title header section just before the function declaration. Local variables should have a description associated with them when they are declared.

Each function and class should have an edit history section where any changes are noted, when the change occurred, and who did it. The line in the code which is changed should be marked with the date and the user's initials. When a new version of the code comes out, the edit histories can be cleared.

Variables

Variable names will follow a slightly simplified Hungarian notation. We will not differentiate between all possible variable types because I don't think it's necessary. The names themselves should be descriptive. They should begin with a prefix which identifies their type. After the prefix, each word should begin with a capital letter. The prefixes are as follows:

  • b - boolean
  • c - character or character string
  • str -C++ string or AnsiString
  • i - integer
  • f - floating point, all precisions
  • fs - file stream
  • io - input or output stream
  • cl - class
  • o - object
  • stc - structure

In addition, the variable should have an additional letter if it is one of the following:

  • m_ - member variable of a struct or class
  • p_ - pointer, either to an individual thing or an array

Strictly avoid single letter variable names except for loop counters. This should include published model parameter variables, even if those are single letters.

Example: iSampleInt, m_cSampleClassMemberChar, clSampleClass, p_oSamplePointerToObject.

Note - I wrote this about naming conventions before I wrote most of the code. It was a while ago and I realize I didn't strictly stick to this. But it is the ideal and I may bring old code into line when I modify it.

Functions

Function names should be descriptive. They should begin with an uppercase letter and multiple words should be distinguished with uppercase letters, as in SampleFunctionName().

Constants

Constant names should appear in all upper-case.


16-Feb-2005 10:32 AM