<!-- doc/src/sgml/sources.sgml -->

 <chapter id="source">
  <title>PostgreSQL Coding Conventions</title>

  <sect1 id="source-format">
   <title>Formatting</title>

   <para>
    Source code formatting uses 4 column tab spacing, with
    tabs preserved (i.e., tabs are not expanded to spaces).
    Each logical indentation level is one additional tab stop.
   </para>

   <para>
    Layout rules (brace positioning, etc.) follow BSD conventions.  In
    particular, curly braces for the controlled blocks of <literal>if</literal>,
    <literal>while</literal>, <literal>switch</literal>, etc. go on their own lines.
   </para>

   <para>
    Limit line lengths so that the code is readable in an 80-column window.
    (This doesn't mean that you must never go past 80 columns.  For instance,
    breaking a long error message string in arbitrary places just to keep the
    code within 80 columns is probably not a net gain in readability.)
   </para>

   <para>
    To maintain a consistent coding style, do not use C++ style comments
    (<literal>//</literal> comments).  <application>pgindent</application>
    will replace them with <literal>/* ... */</literal>.
   </para>

   <para>
    The preferred style for multi-line comment blocks is
<programlisting>
/*
 * comment text begins here
 * and continues here
 */
</programlisting>
    Note that comment blocks that begin in column 1 will be preserved as-is
    by <application>pgindent</application>, but it will re-flow indented comment blocks
    as though they were plain text.  If you want to preserve the line breaks
    in an indented block, add dashes like this:
<programlisting>
    /*----------
     * comment text begins here
     * and continues here
     *----------
     */
</programlisting>
   </para>

   <para>
    While submitted patches do not absolutely have to follow these formatting
    rules, it's a good idea to do so.  Your code will get run through
    <application>pgindent</application> before the next release, so there's no point in
    making it look nice under some other set of formatting conventions.
    A good rule of thumb for patches is <quote>make the new code look like
    the existing code around it</quote>.
   </para>

   <para>
    The <filename>src/tools/editors</filename> directory contains sample settings
    files that can be used with the <productname>Emacs</productname>,
    <productname>xemacs</productname> or <productname>vim</productname>
    editors to help ensure that they format code according to these
    conventions.
   </para>

   <para>
    If you'd like to run <application>pgindent</application> locally
    to help make your code match project style, see
    the <filename>src/tools/pgindent</filename> directory.
   </para>

   <para>
    The text browsing tools <application>more</application> and
    <application>less</application> can be invoked as:
<programlisting>
more -x4
less -x4
</programlisting>
    to make them show tabs appropriately.
   </para>
  </sect1>

  <sect1 id="error-message-reporting">
   <title>Reporting Errors Within the Server</title>

   <indexterm>
    <primary>ereport</primary>
   </indexterm>
   <indexterm>
    <primary>elog</primary>
   </indexterm>

   <para>
    Error, warning, and log messages generated within the server code
    should be created using <function>ereport</function>, or its older cousin
    <function>elog</function>.  The use of this function is complex enough to
    require some explanation.
   </para>

   <para>
    There are two required elements for every message: a severity level
    (ranging from <literal>DEBUG</literal> to <literal>PANIC</literal>, defined
    in <filename>src/include/utils/elog.h</filename>) and a primary
    message text.  In addition there are optional elements, the most
    common of which is an error identifier code that follows the SQL spec's
    SQLSTATE conventions.
    <function>ereport</function> itself is just a shell macro that exists
    mainly for the syntactic convenience