doc/conventions.txt

   1 (Preliminary; still need to be modified and voted on).
   2
   3 Development Conventions
   4 =======================
   5
   6 1.  Indent by increments of four (tabsize of 8).
   7
   8 2.  Use "char* x" rather than "char *x".
   9
  10 3.  Put opening brace on a line by itself.
  11
  12 4.  ThisIsAClassName - no underscores.
  13
  14 5.  thisIsAMethodName() - no underscores.
  15
  16 6.  Lines should not span more than 80 columns.
  17
  18 7.  When methods span more than 80 columns, do this:
  19
  20         void MyClass::myMethod(
  21             const char* someReallyLongName,
  22             const char* someOtherReallyLongName);
  23
  24 8.  Use const whenever possible.
  25
  26 9.  Use const methods whenever possible.
  27
  28 10. Braces must be aligned with control keyword:
  29
  30         for(...)
  31         {
  32         }
  33
  34     Not this:
  35
  36         for (...)
  37           {
  38           }
  39
  40 11. No spaces after names:
  41
  42         Not "void f ()" but "void f()".
  43
  44 12. Avoid this:
  45
  46         callingMyFunction(blah,
  47                           blah2,
  48                           blah3);
  49
  50     Do this:
  51
  52         callingMyFunction(
  53             blah,
  54             blah2,
  55             blah3);
  56
  57 13. Avoid this:
  58
  59         int        x;
  60         float      y;
  61
  62 14. Use 0 and not NULL.
  63
  64 15. Don't commit anything that breaks the build (try a clean slate
  65     checkout and build).
  66
  67 16. Files should take advantage of case and avoid underscores.
  68     Files should have the same name as the class (and same case).
  69
  70 17. Separate functions with blank lines.
  71
  72     class X
  73     {
  74     public:
  75
  76         void f();
  77
  78         void g();
  79     };
  80
  81 18. No warnings should be committed.
  82
  83 19. Test big changes on at least Windows and Unix (or Linux)
  84
  85 20. Move SLP out of Common.
  86
  87 21. Changes must work on all platforms. Commits must not break any
  88     platform.
  89
  90 22. No binaries may be committed to repository.
  91
  92 24. Don't separate return type onto its own line:
  93
  94     Avoid this:
  95
  96         int
  97         f()
  98         {
  99         }
 100
 101
 102 25. All code must be reachable (built) from master makefile. Otherwise
 103     it will not be reached when doing mass substitutions, testings of
 104     builds, and license changes.
 105
 106 26. Prepend '_' to private members (including methods).
 107
 108 27. Use /** */ rather than /// for DOC++.
 109
 110 29. Always write a regression test for everything.
 111
 112 30. Always build and run all regression tests before committing.
 113
 114 31. Be mindful that the tests must run on all supported platforms and
 115     that a commit may break another platform.
 116
 117 33. Tests must clean up the effect they have on the repository.
 118
 119 34. Avoid use of condiational compilation for obscuring platrform
 120     differences. Use (or put) routines in appropriate platform files
 121     or in the System*.cpp files in Common.
 122
 123 --------------------------------------------------------------------------------
 124
 125 34. Use this comment style for DOC++ comments:
 126
 127     class X
 128     {
 129     public:
 130
 131         /** Creates widgets.
 132             @param numWidgets the number of widgets to create.
 133             @return true on success.
 134         */
 135         void createWidgets(Uint32 numWidgets);
 136     };
 137
 138 35. Never use full quotes in includes in header files. Use the angle brackets
 139     and hence use the fully qualified path.
 140
 141         #include <Pegasus/MyModule/Erp.h>
 142
 143     Not
 144
 145         #include "Erp.h"
 146
 147 34. Explain use of Linkage.h files
 148
 149 35. Don't use ultostr(), use sprintf().
 150
 151 36. main() must return something (for NT).