Main CodingConventions

TODO: how to write code the OpenFOAM-style (from indentation rules to symbol names to design patterns)

1 General

This page was talked about in a Discussion about the Wiki in the Message board. Henry Weller gave me the reply I quote below.

The bottom line (as I understand it) is:

• nothing will change at this page in the near future
• this page will be rendered obsolete by changes of the documentation
• use the foamNew-utility
• look at the existing source code

This is Henry's reply:

As far as possible I have implemented and encouraged the use of a consistent style. Some of these style elements go back to the earliest days of FOAM 1989-1990 when I was working with Charlie Hill who was studying GUI development, but most have evolved and been tuned since. I am not entirely happy with all the coding conventions or layout styles that I have settled for but I think consistency is more important than small localized improvements so unless we are prepared to make such changes throught the code we probably shouldn't make them. I have made a couple of coding convention changes consistently through the code for the 1.2, and these I will document in the release notes. Such changes are very time consuming to make given the current size of this project but I considered these to be important enough to warrant the effort.

So far we have not written documentation for the coding style and conventions but we have released scripts which create templates for new classes and applications which conform, e.g.

 
foamNew H newClass
foamNew C newClass
foamNew IO newClass
foamNew I newClass
foamNew App newApp

We intend to extend this principle further by writing scripts to create templates for new run-time selectable modules e.g. boundary-conditions, thermophysical models, turbulence models etc. etc. but we haven't had time so far and have decided to make these and documentation of the coding style and conventions part of the programmers guide which we will start writing as soon as we find sponsorship for this work.

2 Indentation

The indentation of a C++-program doesn't affect the syntactical correctness of that program. The programmer may thus use their own preferred indentation style. However, when collaborating with others or when working within an existing code base it improves the code comprehension if the dominant style is followed.

Some editors (such as XEmacs) assist you with the indentation of the source. Problems arise if one changes a OpenFOAM-source-file because the text-editor might mess up the source-file, making it difficult to track changes with the original.

2.1 Emacs/XEmacs

For the various Emacs flavours, a solution exists and is found here.

2.2 Jed/Xjed

The jed editor is a smallish editor with various style key bindings (including emacs-like). The normal distribution includes both foam (ie, OpenFOAM) and kw (KitWare) c-mode indentation styles, which makes it a fairly useful editor for both of these projects.

The foam style matches the OpenFOAM indentation style for a very large majority of C++ constructs.

For easier switching between c-mode styles, simply use the following define (eg, added to your ~/.jedrc):

   define foam()
   {
       eval (".c_mode \"foam\" c_set_style");
   }

Which can be invoked with the standard mechanism:

   M-x foam

Since OpenFOAM avoids tabs in the source code, it is best to turn them off:

   USE_TABS = 0;  % no tabs for indentation

Additionally, for cleaner code (and to avoid spurious changes), it's a good idea to highlight trailing whitespace and tabs:

   Highlight_Whitespace = 3;     % 1=trailing whitespace, 2 = tabs, 3 = both