From c8057fc5efc6275ac05351d1ea79c49a295efc05 Mon Sep 17 00:00:00 2001
From: Thomas White <taw@physics.org>
Date: Thu, 26 May 2011 15:34:00 +0200
Subject: Update coding standards

---
 doc/reference/xml/coding-standards.xml | 26 +++++++++++++++++++++-----
 1 file changed, 21 insertions(+), 5 deletions(-)

(limited to 'doc')

diff --git a/doc/reference/xml/coding-standards.xml b/doc/reference/xml/coding-standards.xml
index 242719de..d51ba293 100644
--- a/doc/reference/xml/coding-standards.xml
+++ b/doc/reference/xml/coding-standards.xml
@@ -60,7 +60,7 @@ void somefunction(int something)
 However, code must be <emphasis>strictly</emphasis> wrapped at 80 columns, or
 what would be 80 columns if the tabs were displayed as 8 spaces.
 If you think you need more width, you're at too many levels of indentation and
-need to break things down a bit.
+need to break things down a bit.  There are no exceptions whatsoever.
 </para>
 <para>
 When performing a two or three dimensional iteration, for example over image
@@ -112,10 +112,19 @@ void somefunction(int someparam)
 /* Comments use proper capitalisation to make things look neat */
 </programlisting>
 </para>
-<para>
-'struct' blocks can have the braces like functions or 'if' statements.  Usually
-the former looks nicer if the struct is large.
-</para>
+<para>'struct' blocks can have the braces like functions or 'if' statements.  Usually the former looks nicer if the struct is large.</para>
+<para>Parentheses should have spaces after them in 'if' statements, but not in function calls. Function arguments should have spaces after the comma.  There should be no space between the function name and the opening bracket.  That means:</para>
+<para><programlisting>
+if ( something ) {
+	do_something(a, b, c);
+}
+</programlisting></para>
+<para>instead of:</para>
+<para><programlisting>
+if (something) {
+	do_something (a,b,c);
+}
+</programlisting></para>
 </refsect1>
 
 
@@ -129,6 +138,13 @@ prove it here.  As a general rule, if you think you're about to do something cle
 </refsect1>
 
 
+<refsect1 id="CrystFEL-coding-standards.commitmessages">
+<title>VCS commit messages</title>
+<para>The first line of your commit message should include a one line summary of the changes, in the form "Do XYZ".  That is, not "Did XYZ".</para>
+<para>Make the minimum possible changes in each commit.  Try to really distill your changes down to the bare bones, and keep 'cleaning up' in separate commits.  Remember that Git thinks about 'changes' rather than 'versions'.</para>
+</refsect1>
+
+
 <refsect1 id="CrystFEL-coding-standards.evilness">
 <title>Evil dictator</title>
 <para>
-- 
cgit v1.2.3