From 2cf3f6694fc85040c1609c39ca45e7e1f05dea05 Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Sun, 7 Sep 2008 02:01:04 +0000
Subject: [PATCH] Add a few more details in the source-code-formatting
documentation. This isn't exhaustive but it covers some of the more common
layout mistakes I've seen in submitted patches.
---
doc/src/sgml/sources.sgml | 52 +++++++++++++++++++++++++++++++--------
1 file changed, 42 insertions(+), 10 deletions(-)
diff --git a/doc/src/sgml/sources.sgml b/doc/src/sgml/sources.sgml
index 78d60bb5ae4..e78e59ad900 100644
--- a/doc/src/sgml/sources.sgml
+++ b/doc/src/sgml/sources.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/sources.sgml,v 2.30 2008/03/24 18:08:47 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/sources.sgml,v 2.31 2008/09/07 02:01:04 tgl Exp $ -->
<chapter id="source">
<title>PostgreSQL Coding Conventions</title>
@@ -7,24 +7,56 @@
<title>Formatting</title>
<para>
- Source code formatting uses 4 column tab spacing, with
- tabs preserved (i.e. tabs are not expanded to spaces).
+ 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.
- Layout rules (brace positioning, etc) follow BSD conventions.
+ </para>
+
+ <para>
+ Layout rules (brace positioning, etc) follow BSD conventions. In
+ particular, curly braces for the controlled blocks of <literal>if</>,
+ <literal>while</>, <literal>switch</>, etc go on their own lines.
+ </para>
+
+ <para>
+ Do not use C++ style comments (<literal>//</> comments). Strict ANSI C
+ compilers do not accept them. For the same reason, do not use C++
+ extensions such as declaring new variables mid-block.
+ </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</>, 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</>, so there's no point in making it look nice
- under some other set of formatting conventions.
+ <application>pgindent</> before the next release, so there's no point in
+ making it look nice under some other set of formatting conventions.
</para>
<para>
- The <filename>src/tools</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
+ The <filename>src/tools</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>
--
GitLab