Clang Format Text Style

1. Clang-format: ADIOS2 uses the clang-format tool to automatically enforce source code style and formatting rules. There are various ways to integrate the clang-format tool into your IDE / Code Editor depending on if you use Emacs, Vim, Eclipse, KDevelop, Microsoft Visual Studio, etc. that are a bit outside the scope of this document but a quick google search for "integrate clang-format" should point you in the right direction. Main points:

   • Lines no longer than 80 characters.
   • Always use braces { and }, even for 1 line if blocks.
     • Don't

       if( number != 1 )
           number = 1;

     • Do

       if( number != 1 )
       {
           number = 1;
       } 

   • Use 4 spaces for indentation.
   • However, you can always reformat the code manually by running:

     clang-format -i SourceFile.cpp SourceFile.h
     

2. Naming: Use meaningful English words, well-known acronyms (MPI, XML, CFD, GMRES, etc.), or well-known short names (Config, Comm, 2D, 3D).

   • Examples: initialTime instead of tIni , or work instead of wrk

   • One Exception: when redefining long types with the using keyword reasonable mnemonics and short names are allowed, always document scope.

     // local 2D Vector of doubles  
     using std::vector<std::vector<double>> = vDouble2D;

3. Avoid underscores: adds unnecessary length. Reserve it for prefixes of special cases (see class members and lambda functions). Use upper case letters instead.

   • Don't

     std::vector<std::vector<<double>> this_is_my_very_very_long_two_dimensional_vector_name;

   • Do

     std::vector<std::vector<<double>> thisIsMyVeryVeryLongTwoDimensionalVectorName;

4. Using and typedef keywords: Prefer the keyword using over typedef for readability. Only rename very long complex or custom types, do not rename standard types (int, double, std::vector<double>). Prefer including ADIOSTypes.h as it contains fixed types in the std:: namespace (e.g. uint8_t, uint64_t ).

   • Don't

     typedef std::vector<std::vector<std::map<std::string, double>>> MapIn2DVector; 

   • Do

     using std::vector<std::vector<std::map<std::string, double>>> = MapIn2DVector;