home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / xwphescr.zip / XWPH0208.ZIP / CodingConventions.txt next >
Text File  |  2002-03-16  |  5KB  |  155 lines
  1.  
  2. XWorkplace/WarpIN Coding Conventions
  3. (W) Ulrich Möller, March 13, 2000
  4. Last updated January 22, 2001 Ulrich Möller
  5.  
  6. When adding code to XWorkplace, WarpIN, or the XWorkplace helpers,
  7. please follow the coding conventions outlined below.
  8.  
  9. Yes, I know everyone has his/her favorite coding style. This is
  10. a likely topic to cause endless debate, but if you contribute to
  11. my projects... please follow my style.
  12.  
  13. In addition to consistency, this is very helpful for automatic code
  14. documentation through xdoc. See tools/xdoc in the WarpIN source tree
  15. for more about that utility.
  16.  
  17. Here we go:
  18.  
  19.     1.  Use a tab size of 4. Use real spaces instead of tabs.
  20.  
  21.     2.  Align parameters vertically with function calls, at least
  22.         in function headers:
  23.  
  24.             int StoreExecuteRexxCode(const char *pcszName,
  25.                                      const char *pcszCode,
  26.                                      const char *pcszArgs,
  27.                                      char **ppszRet);
  28.  
  29.         Add xdoc documentation to all functions and parameters,
  30.         as outlined below.
  31.  
  32.     3.  Brackets style:
  33.  
  34.                 if (condition)
  35.                 {
  36.                     // do this
  37.                 }
  38.                 else
  39.                 {
  40.                     // do that
  41.                 }
  42.  
  43.         You may leave out brackets if there's only one statement
  44.         after if or else, of course, but with nested if statements,
  45.         I usually add them even in that case since it's so easy
  46.         to mismatch the nesting then.
  47.  
  48.     4.  switch/case style:
  49.  
  50.                 switch (msg)
  51.                 {
  52.                     case WM_CREATE:
  53.                         // code
  54.                     break;
  55.  
  56.                     case WM_DESTROY:
  57.                         // code
  58.                     break;
  59.                 }
  60.  
  61.     5.  For all variables, use the usual OS/2 type prefixes.
  62.         Here are some:
  63.  
  64.         CHAR    c       (char)
  65.         PSZ     psz     (char* pointer)
  66.         PCSZ    pcsz    (const char* pointer)
  67.  
  68.         USHORT  us      (unsigned short)
  69.         SHORT   s       (short)
  70.         ULONG   ul      (unsigned long)
  71.         LONG    l       (long)
  72.         BYTE    b       (byte)
  73.  
  74.         BOOL    f       (flag)
  75.         LONG    fl      (for LONG's containing OR'ed flags)
  76.         SHORT   fs      (for SHORT's containing OR'ed flags)
  77.  
  78.         string/BSString str (C++ string class instance)
  79.  
  80.         For arrays, prefix "a" (e.g. USHORT ausThings[3]).
  81.         For pointers, prefix "p" (e.g. USHORT *pausThings[3]).
  82.  
  83.     6.  Prefix C++ class member variables with an underscore ("_").
  84.         This allows people who are not familiar with the class
  85.         interface to identify member variables easily. Also, this
  86.         has a certain consistency with SOM/WPS class member
  87.         variables.
  88.  
  89.     7.  Prefix global variables with "G_" for the same reason.
  90.         Global variables are potentially dangerous, so these
  91.         can be more easily identified.
  92.  
  93.     8.  Comment your functions in xdoc-style. See any function
  94.         in the sources for how this can be done. Basically, use
  95.         /* */-style comments before the function header and
  96.         xdoc tags in that block.
  97.  
  98.         Sorta like this:
  99.  
  100.         /*
  101.          *@@ Create:
  102.          *      create something.
  103.          */
  104.  
  105.         PVOID Create(PVOID pvCreateFrom,    // in: create from
  106.                      PULONG pulCount)       // out: new count
  107.         {
  108.             ... // code, ignored by xdoc
  109.         }
  110.  
  111.         xdoc will even take the parameter descriptions if they
  112.         are specified as above.
  113.  
  114.         tools/xdoc/readme.txt in the WarpIN sources has a more
  115.         detailed description.
  116.  
  117.         I usually only document functions in the source files,
  118.         not in the headers. Even though xdoc will find documentation
  119.         in headers also, changing headers causes recompiles,
  120.         especially with the complex include hierarchy of WarpIN.
  121.         Also, changing code documentation in the sources only
  122.         reduces the amount of code which needs to be committed
  123.         to the CVS server.
  124.  
  125.     9.  When changing code, mark the code as changed in the
  126.         xdoc comment by using something like the following:
  127.  
  128.         @@changed V0.9.2 (2000-03-10) [umoeller]: fixed memory leak
  129.             |        |        |          |          |
  130.             |        |        |          |          +-- description
  131.             |        |        |          |
  132.             |        |        |          +- author tag (same as CVS login)
  133.             |        |        |
  134.             |        |        +-- ISO date (year, month, day)
  135.             |        |
  136.             |        +-- XWorkplace/WarpIN version number
  137.             |
  138.             +-- xdoc tag ("@@changed" or "@@added")
  139.  
  140.         xdoc can create a full change log if these things are set
  141.         properly. Try "createdoc.cmd" or "createchangelog.cmd" in
  142.         the WarpIN and XWorkplace main source directories,
  143.         respectively.
  144.  
  145.         Also, this way I can do a simple search over all files
  146.         to update the readme with changes and bugfixes for the new
  147.         version.
  148.  
  149.     10. When adding a new function, use the same, just use @@added
  150.         instead of @@changed.
  151.  
  152. Thank you!
  153.  
  154.  
  155.