CODING.STD

   1 CATDOC CODING STANDARD
   2 ~~~~~~~~~~~~~~~~~~~~~~
   3 0. CATDOC ISN'T WRITTEN ON C++!!!
   4    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   5    C and C++ are different languages.
   6    No // comments, no references, no declaration in the middle of block.
   7
   8 1. Catdoc is portable program.
   9 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  10 Please never make following assumptions:
  11 1. That int is more than 16-bit wide
  12  (consequentually, that signed int can hold Unicode character)
  13 2. That sizeof(int)>=sizeof(int *)
  14 3. That int is always 16-bit (it can be 32 bit as well)
  15 4. That long is 32-bit
  16 5. That char (and int and short as well) is either signed or unsigned
  17    Always use explicit signedness specifier
  18 6. That integer arithmetic is 32-bit long.
  19 7. That input is always seekable. Catdoc is often used as filter
  20 8. That filenames are either case-sensitive or case-insensitive
  21 9. That there is no difference between binary and text file opening mode
  22 10. That opening file in the text mode will do something reasonable.
  23     Always open files in binary mode. This is only way to produce
  24         results, consistent on all platforms.
  25 11. That you can rely on compiler POSIX or C99 compliance. If you need
  26    to use some function defined by this standard, write configure test
  27    and provide fallback.
  28 12. That you can allocate chunk of memory larger than 64K.
  29 13. That filenames can be longer that 8+3.
  30
  31 2. Catdoc is used world-wide
  32 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  33
  34 1. Never write comments on languages other than English.
  35 2. Never assume that you can output character without passing it through
  36    convert_char function.
  37
  38 3. Code formatting
  39 ~~~~~~~~~~~~~~~~~
  40 1. Use <Tab> for identation. If your text editor insists on <Tab> being
  41    8 char, consider using some other editor. vim is at least a bit more
  42    portable than catdoc.
  43 2. Open curly bracket on the same line as statement it belongs to:
  44         if (condition) {
  45                 code
  46         }
  47    rather than
  48         if (condition)
  49         {
  50                 code
  51         }
  52
  53 3. The only exeception from rule 2 are blocks in the switch statement:
  54         switch (var) {
  55                 case value:
  56                 {
  57                         code
  58                 }
  59         }
  60         rather than
  61         switch (var) {
  62                 case value: {
  63                                                 code
  64                                         }
  65         }
  66
  67 4. Write comments at the start of each function describing its purpose
  68    and arguments.
  69
  70 5. If you use some potentially dangerous construct, such as sprintf on
  71         static buffer, comment why it is safe in this particular case.
  72