auth/spnego: use better variable names in gensec_spnego_create_negTokenInit()

[sfrench/samba-autobuild/.git] / README.Coding

diff --git a/README.Coding b/README.Coding
index 107856e45f17c78cdec8acada0ea0e66282cfec9..19a363fa1dd13d3f605fc9c009a55fae17cb79ac 100644 (file)
--- a/README.Coding
+++ b/README.Coding
@@ -26,9 +26,6 @@ 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.
 
 If you have ever worked on another free software Python project, you are
 probably already familiar with it.
 

-We try to stay compatible with Python 2.4, so please don't rely on any
-features that were introduced later, such as the "with" statement.
-

 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.
 


@@ -93,6 +90,16 @@ displaying trailing whitespace:
   set textwidth=80
   autocmd BufNewFile,BufRead *.c,*.h exec 'match Todo /\%>' . &textwidth . 'v.\+/'
 
   set textwidth=80
   autocmd BufNewFile,BufRead *.c,*.h exec 'match Todo /\%>' . &textwidth . 'v.\+/'
 

+clang-format
+------------
+BasedOnStyle: LLVM
+IndentWidth: 8
+UseTab: true
+BreakBeforeBraces: Linux
+AllowShortIfStatementsOnASingleLine: false
+IndentCaseLabels: false
+BinPackParameters: false
+

 
 =========================
 FAQ & Statement Reference
 
 =========================
 FAQ & Statement Reference


@@ -192,7 +199,13 @@ characters or less with whitespace.  For example,
 The previous example is intended to illustrate alignment of function
 parameters across lines and not as encourage for gratuitous line
 splitting.  Never split a line before columns 70 - 79 unless you
 The previous example is intended to illustrate alignment of function
 parameters across lines and not as encourage for gratuitous line
 splitting.  Never split a line before columns 70 - 79 unless you

-have a really good reason.  Be smart about formatting.
+have a really good reason. Be smart about formatting.
+
+One exception to the previous rule is function declarations and
+definitions. In function declarations and definitions, either the
+declaration is a one-liner, or each parameter is listed on its own
+line. The rationale is that if there are many parameters, each one
+should be on its own line to make tracking interface changes easier.

 
 
 If, switch, & Code blocks
 
 
 If, switch, & Code blocks


@@ -283,8 +296,8 @@ Good Examples:
                int ret = 0;
 
                if (y < 10) {
                int ret = 0;
 
                if (y < 10) {

-                       z = malloc(sizeof(int)*y);
-                       if (!z) {
+                       z = malloc(sizeof(int) * y);
+                       if (z == NULL) {

                                ret = 1;
                                goto done;
                        }
                                ret = 1;
                                goto done;
                        }


@@ -293,7 +306,7 @@ Good Examples:
                print("Allocated %d elements.\n", y);
 
         done:
                print("Allocated %d elements.\n", y);
 
         done:

-               if (z) {
+               if (z != NULL) {

                        free(z);
                }
 
                        free(z);
                }
 


@@ -301,25 +314,6 @@ Good Examples:
        }
 
 
        }
 
 

-Checking Pointer Values
------------------------
-
-When invoking functions that return pointer values, either of the following
-are acceptable. Use your best judgement and choose the more readable option.
-Remember that many other persons will review it:
-
-       if ((x = malloc(sizeof(short)*10)) == NULL ) {
-               fprintf(stderr, "Unable to alloc memory!\n");
-       }
-
-or:
-
-       x = malloc(sizeof(short)*10);
-       if (!x) {
-               fprintf(stderr, "Unable to alloc memory!\n");
-       }
-
-

 Primitive Data Types
 --------------------
 
 Primitive Data Types
 --------------------
 


@@ -334,6 +328,17 @@ lib/replace/, new code should adhere to the following conventions:
   * Boolean values are "true" and "false" (not True or False)
   * Exact width integers are of type [u]int[8|16|32|64]_t
 
   * Boolean values are "true" and "false" (not True or False)
   * Exact width integers are of type [u]int[8|16|32|64]_t
 

+Most of the time a good name for a boolean variable is 'ok'. Here is an
+example we often use:
+
+       bool ok;
+
+       ok = foo();
+       if (!ok) {
+               /* do something */
+       }
+
+It makes the code more readable and is easy to debug.

 
 Typedefs
 --------
 
 Typedefs
 --------


@@ -342,6 +347,39 @@ Samba tries to avoid "typedef struct { .. } x_t;" so we do always try to use
 "struct x { .. };". We know there are still such typedefs in the code,
 but for new code, please don't do that anymore.
 
 "struct x { .. };". We know there are still such typedefs in the code,
 but for new code, please don't do that anymore.
 

+Initialize pointers
+-------------------
+
+All pointer variables MUST be initialized to NULL. History has
+demonstrated that uninitialized pointer variables have lead to various
+bugs and security issues.
+
+Pointers MUST be initialized even if the assignment directly follows
+the declaration, like pointer2 in the example below, because the
+instructions sequence may change over time.
+
+Good Example:
+
+       char *pointer1 = NULL;
+       char *pointer2 = NULL;
+
+       pointer2 = some_func2();
+
+       ...
+
+       pointer1 = some_func1();
+
+Bad Example:
+
+       char *pointer1;
+       char *pointer2;
+
+       pointer2 = some_func2();
+
+       ...
+
+       pointer1 = some_func1();
+

 Make use of helper variables
 ----------------------------
 
 Make use of helper variables
 ----------------------------
 


@@ -351,7 +389,8 @@ it's also easier to use the "step" command within gdb.
 
 Good Example:
 
 
 Good Example:
 

-       char *name;
+       char *name = NULL;
+       int ret;

 
        name = get_some_name();
        if (name == NULL) {
 
        name = get_some_name();
        if (name == NULL) {


@@ -367,6 +406,33 @@ Bad Example:
        ret = some_function_my_name(get_some_name());
        ...
 
        ret = some_function_my_name(get_some_name());
        ...
 

+Please try to avoid passing function return values to if- or
+while-conditions. The reason for this is better handling of code under a
+debugger.
+
+Good example:
+
+       x = malloc(sizeof(short)*10);
+       if (x == NULL) {
+               fprintf(stderr, "Unable to alloc memory!\n");
+       }
+
+Bad example:
+
+       if ((x = malloc(sizeof(short)*10)) == NULL ) {
+               fprintf(stderr, "Unable to alloc memory!\n");
+       }
+
+There are exceptions to this rule. One example is walking a data structure in
+an iterator style:
+
+       while ((opt = poptGetNextOpt(pc)) != -1) {
+                  ... do something with opt ...
+       }
+
+But in general, please try to avoid this pattern.
+
+

 Control-Flow changing macros
 ----------------------------
 
 Control-Flow changing macros
 ----------------------------
 


@@ -379,15 +445,21 @@ The only exception is the test code that depends repeated use of calls
 like CHECK_STATUS, CHECK_VAL and others.
 
 
 like CHECK_STATUS, CHECK_VAL and others.
 
 

-Function names in DEBUG statements
-----------------------------------
+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:
+Use these following macros instead of DEBUG:

 
 

-Bad Example:
-       DEBUG(0, ("strstr_m: src malloc fail\n"));
+DBG_ERR        log level 0             error conditions
+DBG_WARNING    log level 1             warning conditions
+DBG_NOTICE     log level 3             normal, but significant, condition
+DBG_INFO       log level 5             informational message
+DBG_DEBUG      log level 10            debug-level message

 
 

-Good Example:
-       DEBUG(0, ("%s: src malloc fail\n", __func__));
+Example usage:
+
+DBG_ERR("Memory allocation failed\n");
+DBG_DEBUG("Received %d bytes\n", count);
+
+The messages from these macros are automatically prefixed with the
+function name.