Minimal Coding Conventions

Just about everyone in the VRL ends up re-using code and programs that someone else wrote previously, and undoubtedly the code that they write will be used by someone else in the future. Therefore the golden rule applies well to software development in our lab: do unto others as you would have them do unto you. This page records best practices for getting started developing software in an environment where code lives on through many generations of researchers.

The primary things to keep in mind are that:

Future users of your code need read and write permission; and
Future users of your code can't read your mind, so it must be organized and well-documented.

Minimal Coding Conventions

Tabs are only meaningful in your edit session.

Do not use tabs (except in Makefiles as needed). Indent 4 spaces, but 3 is okay if you prefer.

Name script files with suffixes.

Use Python for scripts (very portable). Avoid reliance on Cygwin.

Commenting code does not slow progress.

If you make it a habit it speeds things up. At a minimum write a method’s purpose and parameter usage.

Linux file system links are not portable. Never use them.

Coding in C++

Use .cpp and .h suffixes for c++ source file names. Not: .C and .H

Avoid conditional compilation (#ifdef).

Use brackets around code bodies over multiple lines.

Evil:     if   (condition)
               action;

Good:     if   (condition)   action;            if  (condition)  { action };

          if   (condition)                      if  (condition)
          {     action;                         {
          }                                         action;
                                                }

Line up brackets so they are easier to match visually.

Do not #include .cpp files.

Coding Tips

Order #include statements from the most universal to the more specific. The likelihood of interference between headers is diminish and the code is easier to read. For example:

#include  <unistd.h>           // Standard C headers.
#include  <fstream>            // Standard C++ headers
#include  <sys/types.h>        // Low level system headers.

#include  <mri/image.h>        // Common Brown libraries.
#include  <utils/Utils_SVD.h>  // Internal project libraries.

#include  "../setup/setup.h"   // Internal project headers.
#include  "Config.h"           // Headers in the same directory.

The order that libraries are linked to build a program is significant.

In some cases the link order has been established for you when you use the G_USE variable. The LDLIB_VER and LDLIB_PROJECT variables are shorthand for linking the correct versions of libraries.

Libraries are linked in the the order they are listed on the link step. Libraries can contain different methods with the same names. Conflicts are resolved by the link order. Only methods that are referenced by the program or methods in other libraries are linked. Consequently if a method in a library calls a method in a second library then the second library must be listed after the first.

In the link step of a build you will know there is a library out of order or missing if you get error messages regarding undefined references. To fix this locate the library containing the missing method or variable. If the library is not being linked, add it. Otherwise move it back in the link order.

Minimal Coding Conventions