|
1 | | -<!-- $PostgreSQL: pgsql/doc/src/sgml/sources.sgml,v 2.30 2008/03/24 18:08:47 tgl Exp $ --> |
| 1 | +<!-- $PostgreSQL: pgsql/doc/src/sgml/sources.sgml,v 2.31 2008/09/07 02:01:04 tgl Exp $ --> |
2 | 2 |
|
3 | 3 | <chapter id="source"> |
4 | 4 | <title>PostgreSQL Coding Conventions</title> |
|
7 | 7 | <title>Formatting</title> |
8 | 8 |
|
9 | 9 | <para> |
10 | | - Source code formatting uses 4 column tab spacing, with |
11 | | - tabs preserved (i.e. tabs are not expanded to spaces). |
| 10 | + Source code formatting uses 4 column tab spacing, with |
| 11 | + tabs preserved (i.e., tabs are not expanded to spaces). |
12 | 12 | Each logical indentation level is one additional tab stop. |
13 | | - Layout rules (brace positioning, etc) follow BSD conventions. |
| 13 | + </para> |
| 14 | + |
| 15 | + <para> |
| 16 | + Layout rules (brace positioning, etc) follow BSD conventions. In |
| 17 | + particular, curly braces for the controlled blocks of <literal>if</>, |
| 18 | + <literal>while</>, <literal>switch</>, etc go on their own lines. |
| 19 | + </para> |
| 20 | + |
| 21 | + <para> |
| 22 | + Do not use C++ style comments (<literal>//</> comments). Strict ANSI C |
| 23 | + compilers do not accept them. For the same reason, do not use C++ |
| 24 | + extensions such as declaring new variables mid-block. |
| 25 | + </para> |
| 26 | + |
| 27 | + <para> |
| 28 | + The preferred style for multi-line comment blocks is |
| 29 | +<programlisting> |
| 30 | +/* |
| 31 | + * comment text begins here |
| 32 | + * and continues here |
| 33 | + */ |
| 34 | +</programlisting> |
| 35 | + Note that comment blocks that begin in column 1 will be preserved as-is |
| 36 | + by <application>pgindent</>, but it will re-flow indented comment blocks |
| 37 | + as though they were plain text. If you want to preserve the line breaks |
| 38 | + in an indented block, add dashes like this: |
| 39 | +<programlisting> |
| 40 | + /*---------- |
| 41 | + * comment text begins here |
| 42 | + * and continues here |
| 43 | + *---------- |
| 44 | + */ |
| 45 | +</programlisting> |
14 | 46 | </para> |
15 | 47 |
|
16 | 48 | <para> |
17 | 49 | While submitted patches do not absolutely have to follow these formatting |
18 | 50 | rules, it's a good idea to do so. Your code will get run through |
19 | | - <application>pgindent</>, so there's no point in making it look nice |
20 | | - under some other set of formatting conventions. |
| 51 | + <application>pgindent</> before the next release, so there's no point in |
| 52 | +making it look niceunder some other set of formatting conventions. |
21 | 53 | </para> |
22 | 54 |
|
23 | 55 | <para> |
24 | | - The <filename>src/tools</filename> directory contains sample settings |
25 | | - files that can be used with the <productname>emacs</productname>, |
26 | | - <productname>xemacs</productname> or <productname>vim</productname> |
27 | | - editors to help ensure that they format code according to these |
| 56 | + The <filename>src/tools</filename> directory contains sample settings |
| 57 | + files that can be used with the <productname>emacs</productname>, |
| 58 | + <productname>xemacs</productname> or <productname>vim</productname> |
| 59 | + editors to help ensure that they format code according to these |
28 | 60 | conventions. |
29 | 61 | </para> |
30 | 62 |
|
|