Changeset 988 for vendor/current/README.Coding

Timestamp:

Nov 24, 2016, 1:14:11 PM (9 years ago)

Author:

Silvan Scherrer

Message:

Samba Server: update vendor to version 4.4.3

File:

• vendor/current/README.Coding (modified) (6 diffs)

vendor/current/README.Coding

@@ -17 +17 @@
 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.
+
+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
@@ -276 +281 @@
 
                 if (y < 10) {
-                        z = malloc(sizeof(int)*y);
-                        if (!z) {
+                        z = malloc(sizeof(int) * y);
+                        if (z == NULL) {
                                 ret = 1;
                                 goto done;
@@ -286 +291 @@
 
          done:
-                if (z) {
+                if (z != NULL) {
                         free(z);
                 }
 
                 return ret;
-        }
-
-
-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");
         }
 
@@ -335 +321 @@
 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
 ----------------------------
@@ -344 +363 @@
 Good Example:
 
-        char *name;
+        char *name = NULL;
 
         name = get_some_name();
@@ -360 +379 @@
         ...
 
+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
+----------------------------
+
+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.
+
+
+DEBUG statements
+----------------
+
+Use these following macros instead of DEBUG:
+
+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
+
+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.