backported the openbsd fixes from waf 1.7

[obnox/samba/samba-obnox.git] / README.Coding

diff --git a/README.Coding b/README.Coding
index b1ac2fe6666c48429e66c3dac74d45ae522c39e5..0bbba9fc45e5fd756ff2b77df54e86a0cebeb607 100644 (file)
--- a/README.Coding
+++ b/README.Coding
@@ -16,11 +16,16 @@ style should never outweigh coding itself and so the guidelines
 described here are hopefully easy enough to follow as they are very
 common and supported by tools and editors.
 
 described here are hopefully easy enough to follow as they are very
 common and supported by tools and editors.
 

-The basic style, also mentioned in prog_guide4.txt, is the Linux kernel
+The basic style for C code, also mentioned in prog_guide4.txt, is the Linux kernel

 coding style (See Documentation/CodingStyle in the kernel source tree). This
 closely matches what most Samba developers use already anyways, with a few
 exceptions as mentioned below.
 
 coding style (See Documentation/CodingStyle in the kernel source tree). This
 closely matches what most Samba developers use already anyways, with a few
 exceptions as mentioned below.
 

+The coding style for Python code is documented in PEP8,
+http://www.python.org/pep/pep8 (with spaces). 
+If you have ever worked on another free software Python project, you are
+probably already familiar with it.
+

 But to save you the trouble of reading the Linux kernel style guide, here
 are the highlights.
 
 But to save you the trouble of reading the Linux kernel style guide, here
 are the highlights.
 


@@ -94,11 +99,12 @@ Comments
 --------
 
 Comments should always use the standard C syntax.  C++
 --------
 
 Comments should always use the standard C syntax.  C++

-style comments are not currently allowed. The lines before
-a comment should be empty. If the comment directly belongs
-to the following code, there should be no empty line after
-the comment. In case the comment contains a summary of
-mutliple following code blogs.
+style comments are not currently allowed.
+
+The lines before a comment should be empty. If the comment directly
+belongs to the following code, there should be no empty line
+after the comment, except if the comment contains a summary
+of multiple following code blocks.

 
 This is good:
 
 
 This is good:
 


@@ -358,3 +364,27 @@ Bad Example:
        ret = some_function_my_name(get_some_name());
        ...
 
        ret = some_function_my_name(get_some_name());
        ...
 

+Control-Flow changing macros
+----------------------------
+
+Macros like NT_STATUS_NOT_OK_RETURN that change control flow
+(return/goto/etc) from within the macro are considered bad, because
+they look like function calls that never change control flow. Please
+do not use them in new code.
+
+The only exception is the test code that depends repeated use of calls
+like CHECK_STATUS, CHECK_VAL and others.
+
+
+Function names in DEBUG statements
+----------------------------------
+
+Many DEBUG statements contain the name of the function they appear in. This is
+not a good idea, as this is prone to bitrot. Function names change, code
+moves, but the DEBUG statements are not adapted. Use %s and __func__ for this:
+
+Bad Example:
+       DEBUG(0, ("strstr_m: src malloc fail\n"));
+
+Good Example:
+       DEBUG(0, ("%s: src malloc fail\n", __func__));