Ticket #472: codingstyle.txt

File codingstyle.txt, 3.3 kB (added by dmorissette, 4 years ago)

DMSG Coding Style

Line 
1 The rules that MUST be followed:
2 --------------------------------
3
4 1- Make our code fit in 80 columns unless it's not practical to do so
5 because of a long function name or an expression that would become
6 unreadable if broken on several lines.
7
8 2- NO TABS... set your editor to produce spaces instead of tabs...
9 that's because some editors use 4 chars tabs and some use 8 chars and
10 everything looks screwed up if you allow the use of tab chars.
11
12 #1 and #2 are also a requirement with some of our external clients.
13
14 3- Brackets... we use this
15      if (...)
16      {
17          ...;
18      }
19      else
20      {
21          ...;
22      }
23
24 More flexible rules: (some may not apply depending on context)
25 --------------------
26
27 4- Indent is 4 chars usually.  We've used 2 chars in some places but we
28 try to stick to 4.
29
30 5- Use hungarian notation for variables (makes more sense in C than in
31 PHP):
32
33  Prefix     Description
34  ------     ----------------------------
35    b         Boolean
36    c         Char
37    n         Integer value
38    i         Integer, used as a counter in a loop for instance
39              (we also often use the vars i, j, or k for counters)
40    f         Float, single precision
41    d         Double precision Float (we also use "df" sometimes)
42    sz        String zero-terminated (a C string!)
43    by        Byte
44    o         Object
45    s         Structure
46    fp        FILE *
47
48    a         Array of ...
49    p         Pointer to ...
50    
51    k         Constant
52    m         Class member variable (we also use "m_" sometimes)
53    g         Global variable
54
55  Examples:
56  ---------
57    char   szFilename[100];
58    char   *pszFilename;
59    int    nProjectId;
60    int    i, j, k;
61    int    iField;
62    double dX, dY;
63    char   **papszLines;
64    TABFile *poSrcFile;
65    GBool  bSuccess;
66
67
68 6- Function and variable names use upper-lowercase combinations instead
69 of underscores, e.g.  int nProjectId instead of project_id,
70
71 7- Filenames and directory names:
72
73     - Avoid spaces or special non-alphanumerical characters in filenames.
74       The safe characters to use in filenames are "a-z", "0-9", "_" and "."
75
76     - Avoid uppercases in filenames, except for special files that should
77       show up at the top of a directory listing like README.TXT,
78       INSTALL.TXT, etc.  For the rest try to stick to lowercase-only
79       filenames, that makes our lives much easier when porting code
80       between Windows and Unix.
81
82 8- Comments... quite flexible... we most of the time use something like
83 this for function headers:
84
85 /*****************************************************************
86  *                          MyFunction()
87  *
88  * This function will do something pretty cool.  It expects numbers
89  * as arguments and returns a pointer to a buffer newly allocated.
90  *
91  * The caller should free the returned buffer.  NULL is returned in
92  * case of error.
93  *****************************************************************/
94
95 and for comments inline, it's either a short one-line /*... */ thing, or
96 if it's longer then we sometimes use the following to also act as a
97 delimiter of an important part of a function:
98
99 /* --------------------------------------------------------------
100  *  OK, this is an interesting comment...
101  * -------------------------------------------------------------- */
102
103 Some people (Frank and Assefa at least) use some Emacs macros
104 to automatically format these comments.
105
106