begriffs open source - ai-pg/blob - full-docs/txt/source-format.txt

   1
   2 55.1. Formatting #
   3
   4    Source code formatting uses 4 column tab spacing, with tabs preserved
   5    (i.e., tabs are not expanded to spaces). Each logical indentation level
   6    is one additional tab stop.
   7
   8    Layout rules (brace positioning, etc.) follow BSD conventions. In
   9    particular, curly braces for the controlled blocks of if, while,
  10    switch, etc. go on their own lines.
  11
  12    Limit line lengths so that the code is readable in an 80-column window.
  13    (This doesn't mean that you must never go past 80 columns. For
  14    instance, breaking a long error message string in arbitrary places just
  15    to keep the code within 80 columns is probably not a net gain in
  16    readability.)
  17
  18    To maintain a consistent coding style, do not use C++ style comments
  19    (// comments). pgindent will replace them with /* ... */.
  20
  21    The preferred style for multi-line comment blocks is
  22 /*
  23  * comment text begins here
  24  * and continues here
  25  */
  26
  27    Note that comment blocks that begin in column 1 will be preserved as-is
  28    by pgindent, but it will re-flow indented comment blocks as though they
  29    were plain text. If you want to preserve the line breaks in an indented
  30    block, add dashes like this:
  31     /*----------
  32      * comment text begins here
  33      * and continues here
  34      *----------
  35      */
  36
  37    While submitted patches do not absolutely have to follow these
  38    formatting rules, it's a good idea to do so. Your code will get run
  39    through pgindent before the next release, so there's no point in making
  40    it look nice under some other set of formatting conventions. A good
  41    rule of thumb for patches is “make the new code look like the existing
  42    code around it”.
  43
  44    The src/tools/editors directory contains sample settings files that can
  45    be used with the Emacs, xemacs or vim editors to help ensure that they
  46    format code according to these conventions.
  47
  48    If you'd like to run pgindent locally to help make your code match
  49    project style, see the src/tools/pgindent directory.
  50
  51    The text browsing tools more and less can be invoked as:
  52 more -x4
  53 less -x4
  54
  55    to make them show tabs appropriately.