src/STYLE

   1
   2 Coding conventions/style for the ricmsg library.
   3
   4 Line width
   5 A hard line width will not be enforced, but a soft maximum of 150
   6 characters is preferred.
   7
   8
   9 Indention
  10 Indention is with TABS. Tab width is 4. Please ensure the line
  11                 // :vi ts=4 sw=4 noet:
  12 is include in any new source file.
  13
  14
  15 Comments
  16 A "two column" approach is preferred so as to prevent small comments from
  17 disrupting the "flow" of the logic; for example:
  18
  19         switch( *(tokens[0]) ) {
  20                 case 'n':                                                                                               // newrt|{start|end}
  21                         if( strcmp( tokens[1], "end" ) == 0 ) {                         // wrap up the table we were building
  22                                 if( nrt ) {
  23                                         uta_rt_drop( ctx->old_rtable );                         // time to drop one that was previously replaced
  24                                         ctx->old_rtable = ctx->rtable;                          // currently active becomes old and allowed to 'drain'
  25                                         ctx->rtable = nrt;                                                      // one we've been adding to becomes active
  26                                         nrt = NULL;
  27                                 } else {
  28                                         nrt = NULL;
  29                                 }
  30                         } else {                                                                                        // start a new table.
  31                                 if( nrt != NULL ) {                                                             // one in progress?  this forces it out
  32                                         uta_rt_drop( nrt );
  33                                 }
  34
  35 Comment Blocks
  36 Major sections of code may be commented with multi-line blocks. These comments
  37 should be enclosed in /* and */, indented to match the current top line of the block.
  38 Each line should NOT contain a leading * or #, and a row of dashes at the top
  39 and bottom should only be used for critical comments.  For example:
  40
  41         /*
  42                 Return true if routing table is initialised etc. and app can send/receive.
  43         */
  44
  45 Function Headers
  46 All functions should have a header comment block which describes:
  47         - the purpose of the function
  48         - any non-obvious parameters
  49         - parameter limits/values where applicable
  50         - general caution or warning statement to future programmers
  51
  52
  53 Parenthesess and Brackets
  54 When parentheses are used on function calls, if and while statements, there should be
  55 a single space between the opening paraen and first token, and a similar space
  56 between the end of the last token and the closing paren; this makes the code easier
  57 to read in a monochrome environment.
  58
  59 Parentheses used for expressions and type casting should abutt the tokens in the expression,
  60 and further helps to make the code readable when an expression is used in an if/while.
  61 To illustrate:
  62
  63         if( (ctx = (uta_ctx_t *) vctx) == NULL ) {              // this is readable
  64         if((ctx=(uta_ctx_t *)vctx) == NULL) {                   // this is not
  65
  66 Opening parens should NOT be separated from the function or keyword token; 'if(' not
  67 'if ('.
  68
  69 Return is NOT a function, and thus the return value should NOT be placed in parens.
  70
  71
  72 Curly Brace Enclosed Blocks
  73 Go's enforced curly brace policy actually makes senes, so that is used here. The bodies
  74 of ALL if statements, even when just a single line, are to be enclosed in curly braces.
  75 Further, curly braces are placed on the same line as the if and else tokens.  The final
  76 closing curly brace is aligned with the corresponding if. For example:
  77
  78         if( key_len < 10 ) {                                    // TESTING -- use dummy seed function as nn_rcv likley never to find a publisher
  79                 mlen = dummy_nn_rtg_rcv( mbuf );        // TESTING ONLY -- get a seed table
  80                 key_len = 16;                                           // after seeding, we can wait
  81         } else {
  82         mlen = nn_recv( nn_sock, mbuf, sizeof( mbuf )-1, 0 );           // blocks until next buffer
  83         }
  84
  85 Functions
  86 Function types should be placed on the same line as the function name as this allows
  87 for simple generation of prototype statements in the header files.
  88
  89 Variable Declaration and Type Specification
  90 C's variable declaration opens the programmer to a world of accdental maintence bugs
  91 when multple varlables are defined using a comma operator.  Therefore, one variable
  92 definition, per line is to be used here.  Further, pointer types are to be declared
  93 as 'type* var'  rather than 'type *var' because the variable type is a pointer and
  94 declaring it this way envforces it.  Yes, this can lead to issues as 'int* k,n'
  95 isn't what you probalby want, but is exactly why using multiple declarations on a
  96 single line is considered bad.  Again, Go's approach to variable declaration got
  97 this correct.
  98
  99 When declaring types (typedef) the preferred convention is to add "_t" to the type
 100 name; e.g. msg_t.   On the other hand, variable names should NOT indicate the type
 101 (state_b is wrong as state might not always be boolean).
 102
 103 All variables for a function should be declared at the TOP of the function. This makes
 104 maintenence easier, and modern compilers are good at allocating variables as they
 105 enter/leave scope, so there is no reason to allocate variables "script style".
 106 It is also wise to initialise all variables at allocation; use your best judgement.
 107
 108 Camel Case
 109 Sucks; use underbars.
 110         This_is_easy_to_read
 111         ThisIsNotEasyToRead
 112
 113 External names and contants
 114 All outward facing external names and constants will begin with rmr_ or RMR_ as approprate.
 115
 116
 117 Mk and Makefile confentions
 118 Not much here other than there should be 2 "cleanup" rules: clean and nuke. Clean should
 119 remove all intermediate files, leaving desired output (libraries, .ps or .pdf files). The
 120 nuke rule should remove everything that can be built including libraries, binaries, .pdf
 121 files etc.
 122
 123 Mk is preferred as the recipes are easier to define and maintain (no silly end of line
 124 continuation, mkfile variables are passed, etc.).  However, both mkfiles and Makefiles
 125 should be created so as not to require mk.  Yes this is duplicate work, and dropping
 126 make support is certainly acceptable :)