STYLE

   1 $VER OpenBOOPSI Project Style Guide 1.1 (4.5.99)
   2
   3
   4                          OpenBOOPSI Project Style Guide
   5
   6 ----
   7
   8
   9 0. SUMMARY
  10
  11     1. Introduction
  12     2. Comments
  13         2.1 General Rules
  14         2.2 Language
  15         2.3 Single line comments
  16         2.4 Multi line comments
  17     3. Blank Spaces
  18         3.1 Tabs
  19         3.2 Spaces
  20         3.3 Empty lines
  21     4. Naming Conventions
  22         4.1 General Rules
  23         4.2 Functions
  24         4.3 Variables
  25
  26
  27 1. INTRODUCTION
  28
  29     This is a brief guide on recommended source code formatting style
  30     for the OpenBOOPSI Project classes. Every source file added to this
  31     project should conform as close as possible to the rules given in
  32     this document to mantain consistency within the source tree.
  33
  34     It might happen that you're already used to a different coding
  35     style. Yes, we all understand well that changing your style can be
  36     frustrating for any programmer. But the need to keep the source
  37     code style consistent is more important than each one's habits.
  38     No one will blame you if you don't strictly follow these
  39     guidelines, but we will be glad if you do.
  40
  41
  42 2. COMMENTS
  43
  44     2.1 GENERAL RULES
  45
  46         Comment as much as you can. Other programmers will read your
  47         sources and since most of them will have different knowledge of
  48         Amiga programming and/or different ways to do a certain thing they
  49         may not understand the purpose or the inner working of some of your
  50         code, so try to explain what you are doing. Obviously avoid comments
  51         such as "now open a window" right above a OpenWindow() function call.
  52
  53     2.2 LANGUAGE
  54
  55         Comments must be written in english.
  56
  57     2.3 SINGLE LINE COMMENTS
  58
  59         Single line comments should follow the ANSI C syntax, i.e.
  60         using the "/* */" construct. C++ comments must not be used
  61         because not all C compilers do support them.
  62
  63     2.4 MULTI LINE COMMENTS
  64
  65         Comments spanning over multiple lines should be formatted this way:
  66
  67         /* This is a very very very
  68          * very very long comment!
  69          */
  70
  71
  72 3. BLANK SPACES
  73
  74     3.1 TABS
  75
  76         Tabs are four spaces wide.
  77
  78     3.2 SPACES
  79
  80         There should be a space after commas.
  81
  82         There should never be a space after a * when it's used with pointers,
  83         e.g.:
  84
  85         ULONG *pointer = NULL;
  86         *pointer = 45 * y;
  87
  88         There should be a blank space around operators, e.g.:
  89
  90             var1 + var2;
  91             var1 & var2;
  92             etc.
  93
  94         the only exceptions are prefix and postfix ++ and -- operators,
  95         i.e.:
  96
  97             var--;
  98             ++var;
  99
 100         Before a parenthesis there should never be blank spaces if
 101         it follow a keyword or a function name. e.g.
 102
 103             if()              /* good */
 104             DoMethod();       /* also good */
 105             while ()          /* wrong! */
 106             yourfunction ();  /* also wrong! */
 107
 108     3.3 EMPTY LINES
 109
 110         After the #include block and after the #define one there should be
 111         two empty lines.
 112
 113         Between the declaration of the global variables and the beginning of
 114         the code there should be two empty lines.
 115
 116         Between the end of a function and the next one there should be three
 117         empty lines.
 118
 119         Any code block enclosed in braces should be preceded by an empty line.
 120         An open brace should be on a line by itself. After a closing brace there
 121         should be one empty line, except when another closing brace follows. e.g.
 122
 123             if(z == 1)
 124             {
 125                 z++;
 126             }
 127
 128             y += z + 3;
 129
 130             if(y > 8)
 131             {
 132                 f = do_some_stuff();
 133
 134                 if(f == TRUE)
 135                 {
 136                     printf("ok!\n");
 137                 }
 138             }
 139
 140             /* the following is wrong! */
 141
 142             if(y==1) {
 143                 z++;
 144             }
 145             y+=z +3;
 146             if (y >8)
 147             { etc. }
 148
 149
 150 4. NAMING CONVENTIONS
 151
 152     4.3 GENERAL RULES
 153
 154         Everything related to the classes (methods, functions, etc.) should
 155         have a prefix (two or three letter maximum) that recalls the name of
 156         the class. i.e. if your class is called "BananaSplit" its methods
 157         should be called something like BSM_SHAKE, its attributes should look
 158         like BSA_SugarSpuns, etc.
 159
 160     4.2 FUNCTIONS
 161
 162         Method functions should obviously follow the general rule and have
 163         the above mentioned prefix, e.g.:
 164
 165         BS_GoActive();
 166
 167         Function names should have the first letters of each word
 168         forming their names capitalized, like system's one. e.g.:
 169
 170         MyWonderfulFunction()
 171
 172     4.3 VARIABLES
 173
 174         Variables name must be in english and must have a meaning! Please
 175         avoid names such as "foobar" or "dummy"! We hate them!
 176         Some examples:
 177
 178         struct Window *win;       /* these are good */
 179         ULONG  result;
 180
 181         struct BitMap *dummy1;    /* these are wrong! */
 182         struct RastPort *dummy2;
 183
 184         Names of local variables should be all in lowercase. Global
 185         variables should have their initials uppercase.