Merge pull request #372 from nmfs-stock-synthesis/163-new-style

163 new style

Author: Rick-Methot-NOAA

.clang-format

@@ -1,24 +1,25 @@
 ---
 Language:        Cpp
+
 AccessModifierOffset: -4
 AlignAfterOpenBracket: false
 AlignConsecutiveAssignments: false
 AlignEscapedNewlinesLeft: false
 AlignOperands:   false
 AlignTrailingComments: false
 AllowAllParametersOfDeclarationOnNextLine: true
-AllowShortBlocksOnASingleLine: true
+AllowShortBlocksOnASingleLine: false
 AllowShortCaseLabelsOnASingleLine: false
 AllowShortFunctionsOnASingleLine: Empty
-AllowShortIfStatementsOnASingleLine: true
-AllowShortLoopsOnASingleLine: true
+AllowShortIfStatementsOnASingleLine: false
+AllowShortLoopsOnASingleLine: false
 AlwaysBreakAfterDefinitionReturnType: None
 AlwaysBreakBeforeMultilineStrings: false
 AlwaysBreakTemplateDeclarations: false
 BinPackArguments: true
 BinPackParameters: true
 BreakBeforeBinaryOperators: None
-BreakBeforeBraces: Allman
+BreakBeforeBraces: Stroustrup
 BreakBeforeTernaryOperators: false
 BreakConstructorInitializersBeforeComma: true
 ColumnLimit:     0

coding_style.md

@@ -1,41 +1,91 @@
 # Draft programming style for SS3
-Please notice that the term C++ section is used as short-hand for code that is in the LOCAL_CALCS sections of the TPL code.
+SS3 is coded in C++ and ADMB TPL which have different requirements for compilation.
+C++ code is contained in 'LOCAL_CALCS' sections.
+The following is to enhance clarity while building using ADMB tools.
 
-## Math Expressions
-Generally, there is a space on each side of a mathematical operator (+ - * / =).
-This may be dispensed with when the expression is used as an index for an array, vector, matrix, etc.
+## LOCAL_CALCS Sections
+These sections are between the statements 'LOCAL_CALCS' and 'END_CALCS'
+each of which must be one space from the left.
+
+If using clang-format, make
+sure these comments are at the beginning and ending of the section:
+// clang-format on, and
+// clang-format off.
+
+Example:
+
+    LOCAL_CALCS
+     // clang-format on
+     . . .
+      // clang-format off
+     END_CALCS
+
+
+### Math Expressions
+Use spaces on each side of a mathematical operator (+ - * / =), unless
+the expression is used as an index for an array, vector, matrix, etc.
 
 Examples:
 
     n = (maxread-minread) / binwidth2 + 1;
+
     bins(z) = bins(z-1) + width;
 
-## Control Statements
-There can be a space before the left parenthesis and after the right parenthesis. Brackets should always be used and put on their own line (so that the matching brackets are obvious).
+### Control Statements
+Use a space before the left parenthesis and after the right
+parenthesis in control statements (e.g. for, do while, while, if, else).
+
+Use curly braces for all code blocks. For short blocks, they may be on the same line as the conditional statement, but for large blocks, put them on their
+own line (so that the closing curly brace is obvious).
+
+Example:
+
+    if (a > b)
+    {
+      . . . // lots of code
+      b = 2;
+      . . . // more code
+    }
+    else {
+      b = 4;
+    }
 
 #### Logic Expressions
-There is a space on each side of the logical operators (< > <= >= == !=).
-Math expressions used as indices may contain spaces or not depending on what makes it most clear.
+Use a space on each side of the logical operators (< > <= >= == !=).
+Logical expressions used as indices may contain spaces or not
+depending on what makes it most clear.
 
-Examples:  
+Examples:
 
     if (this > that)
+
     for (f = 1; f <= number; f++)
 
-## TPL
+
+## TPL Sections
 TPL sections deserve special consideration.
+While the LOCAL_CALCS section is treated as pure C++ code,
+the other sections of .tpl files are templates that are
+translated to C++ code before compilation, so there are
+additional syntax rules that must be taken into account.
 
 ### Indices
-Items with multiple indices cannot have spaces between them.  
-In C++, spaces can be inserted, e.g. matrix1 (1, j, 5).
-In TPL, the same item would be matrix1(1,j,5). For the sake of consistency, this can be done in the C++ sections also.
+Items with multiple indices cannot have spaces between them.
+In C++, spaces can be inserted, e.g. matrix1 (1, j, 5) while in
+TPL, the same item would be matrix1(1,j,5). For the sake of
+consistency, this can be done in the C++ sections also.
 
 Examples:
 
     vector length(1,nlength);
+    
     ivector parmlist(1,2*number);
 
 ### Semi-colons
-Use semi-colons to end each statement especially if this will be
-passed through the "pretty_tpl" routine. Clang-format will join
-statements together if they are not separated by semi-colons.
+Use semi-colons to end each statement.
+Clang-format will join statements together if they are not separated
+by semi-colons.
+
+## Indenting
+Use 2 spaces to indent each level of code to make it obvious what
+code belongs together.

pretty_tpl.bat

@@ -5,8 +5,14 @@ rem prettify tpl code by running through clang-format
 rem and then tpl-format (to correct issues).
 rem this assumes presence of clang-format.exe, 
 rem tpl-format.exe, and the file .clang-format
+rem
+rem if using LOCAL_CALCS/END_CALCS, clang-format can
+rem only work within those sections. Use // clang-format on
+rem to turn it on after a LOCAL_CALCS and // clang-format off
+rem to turn it off before END_CALCS for normal tpl code.
+rem (Also place a // clang-format off at the beginning of the code).
 rem 
-rem use: pretty_tpl filename 
+rem usage: pretty_tpl filename 
 rem
 echo formatting file %1
 clang-format -i %1