Revision 1494

trunk/docs/developer/ADMBCodingStandards.txt (revision 1494)
1
#ADMB Coding Standards
2

  
3
Coding Standards improve readability and to help insure that code written by multiple authors has the same consistent appearance. 
4

  
5
Below are guidelines and recommendations for writing and maintaining source code.
6

  
7
ADMB uses rules from:
8

  
9
+ "The Elements of C++ Style" by Trevor Misfeldt, Gregory Bumgardner and Andrew Gray. A summary of this references is available on-line.
10

  
11
+ "C++ Coding Standards" by Herb Sutter and Andrei Alexandrescu
12

  
13
+ "Google C++ Style Guide" by Benjy Weinberger, Craig Silverstein,Gregory Eitzmann, Mark Mentovai,Tashana Landray.
14

  
15
##General Principles
16
The most important principles are the first 2 from Misfeldt et al
17

  
18
+ Adhere to the style of the original.
19
+ Adhere to the Principle of Least Astonishment.
20

  
21
##ADMB Coding Standards
22
1. All files should have CR line endings. 
23

  
24
    Windows text files that are opened in unix show *__^M__* characters which makes the file less readable.
25

  
26
    _Note — Exceptions are the windows batch files._
27

  
28
2. Avoid the use of tab character in source files. 
29

  
30
    Tabs display differently in various editors.
31

  
32
3. Use two (2) spaces for indents.
33

  
34
    This is common in most coding standards.  See [Indenting script]() below.
35

  
36
4. Lines should be no longer than 80 characters. 
37

  
38
    This makes it easier to print and display in command line shells.
39

  
40
5. Avoid spaces at the end of lines.
41

  
42
6. Place opening and closing braces on their own line and align them.
43

  
44
    For example. 
45

  
46
        if (x < 0.0)
47
        {
48
          y = a;
49
        }
50
        else
51
        {
52
          y = b * x;
53
        }
54

  
55
    **Indenting script**
56

  
57
    Many linux-like systems have the indent utility. The following bash script produces nice-looking 
58
    code, but it is not perfect, and some additional work with an editor may be required.
59

  
60
        #!/bin/bash
61
        #
62
        # reformats source code to ADMB style using indent
63
        # see http://www.gnu.org/software/indent/
64
        #
65
        # Author: John Sibert
66
        #
67
        cp -v $1 $1.bak
68
        indent -nbad -bap -bbo -nbc -bl -blf -bli0 -bls -c33\
69
         -cd33 -ncdb -ce -ci3 -cli0 -cp33 -cs -d0 -di1 -nfc1\
70
         -nfca -hnl -i3 -ip0 -l75 -lp -npcs -nprs -npsl -saf\
71
         -sai -saw -nsc -nsob -nss $1 -o indent.out
72
        cp -v indent.out $1
73

  
74
7. Avoid mixing lower and uppercase characters in classes and methods (isCamelBack() notation).
75
 
76

  
77
##Naming Conventions
78
+ Adding new functions and files to the trunk
79
+  Adding a new function
80
+ Allocate the file to the source sub-directory (linad99,  sparse, df1b2-separable,  nh99 , tools99)  in the  src directory with most similar content (according to your judgement) and insert your new function there. 
81
+ Avoid duplicating existing functions (do a "grep").
82
+ Include a function declaration in one of the header files:
83
+ If your function is of ordinary ADMB/autodif type (not df1b2) the header file is "src/linad99/fvar.hpp"
84
+ If your function is using one of the df1b2 types (for the random effects stuff) the header file is "src/df1b2-separable/df1b2fun.h"
85
+ When you write a function involving df1b2 objects as arguments (and return type) there always needs to be a complimentary function of ordinary ADMB/autodif variable type. An example of a set of complimentary functions is:
86
+ df1b2vector sin(const df1b2vector&);
87
+ dvar_vector sin(const dvar_vector&);
88
+ Adding new files
89
+ When a new cpp file is added to a directory it must be listed in the "objects.lst" file in that directory in order to be compiled into the libraries. 
90
+ 
91
+ Example: "my_new.cpp" would be listes as "my_new.obj".
92
+ Naming conventions
93
+ Naming conventions .....

Also available in: Unified diff