Changes between Initial Version and Version 1 of CodingStyle

Timestamp:

Apr 25, 2007, 12:29:51 PM (17 years ago)

Author:

Nicolas

Comment:

Converted by an automatic script

CodingStyle

@@ +1 @@
+= BOINC coding style =
+
+
+==  All languages ==
+
+===  Code factoring ===
+
+ * If code is repeated, factor it out and make it into a function
+ * If a function becomes longer than 100 lines or so, split it up
+ * If a file is becoming 'landfill', split it up.
+ * C++ .h files often contain both interface and implementation.         Clearly divide these.
+
+
+===  Code documentation ===
+
+ * .C files have a comment at the top saying what's         in the file (and perhaps what isn't).
+ * Functions are preceded by a comment saying what they do.
+ * Structs and classes are preceded by a comment saying what they are.
+
+
+===  Naming ===
+
+ * Names should be descriptive without being verbose         (local variables names may be short)
+ * Class and type names, and #defined symbols, are all upper case,         with underscores to separate words.
+ * Variable and function names are all lower case,         with underscores to separate words.
+ * No mixed case names
+
+
+===  Indentation ===
+
+ * Each level of indentation is 4 spaces (not a tab).
+ * multi-line function call:
+{{{
+        func(
+            blah, blah, blah, blah, blah,
+            blah, blah, blah, blah, blah
+        );
+        }}}
+ * switch statements: case labels are at same indent level as switch
+{{{
+        switch (foo) {
+        case 1:
+            ...
+            break;
+        case 2:
+            ...
+            break;
+        }
+        }}}
+
+
+===  Constants ===
+
+
+
+===  Braces ===
+
+ * Opening curly brace goes at end of line (not next line):
+{{{
+        if (foobar) {
+            ...
+        } else if (blah) {
+            ...
+        } else {
+            ...
+        }
+    }}}
+ * always use curly braces on multi-line if statements
+{{{
+        if (foo)
+            return blah;        // WRONG
+    }}}
+ * 1-line if() statments are OK:
+{{{
+        if (foo) return blah;
+    }}}
+
+
+===  comments and #ifdefs ===
+
+ * use // for all comments
+ * comment out blocks of code as follows:
+{{{
+        #if 0
+            ...
+        #endif
+    }}}
+
+
+==  C++ specific ==
+
+===  Includes ===
+
+ * A .C file should have the minimum set of #includes to get         that particular file to compile         (e.g. the includes needed by foo.C should be in foo.C, not foo.h)
+ * Includes should go from general (<stdio.h>) to specific (thisfile.h)
+
+
+===  extern declarations ===
+
+
+
+===  Use of static ===
+
+ * if a function or variable is used only in 1 file, declare it static.
+
+
+===  Things to avoid unless there's a truly compelling reason: ===
+
+ * inline functions
+ * operator or function overloading
+ * templates
+
+
+===  Things to avoid ===
+
+ * use typedef (not #define) to define types
+ * don't use memset() or memcpy() to initialize or copy classes         that are non-C compatible.         Write a default constructor and a copy constructor.
+
+
+===  error codes ===
+
+ * (almost) all functions should return an integer error code.         Nonzero means error.         See lib/errornumbers.h for a list of error codes.
+ * Calls to functions that return an error code should         check the code.         Generally they should return on error, e.g.:
+{{{
+            retval = blah();
+            if (retval) return retval;
+    }}}
+
+
+===  structure definitions ===
+
+
+
+{{{
+
+    struct FOO {
+        ...
+    };
+    }}}
+      You can then declare variables as:
+{{{
+    FOO x;
+    }}}
+
+==  PHP specific ==
+
+=== Getting POST and GET data ===
+ Remember that hackers can pass arbitrary values in POST and GET, and they can use this to do SQL injections and other exploits.
+ * Do not access $_POST or $_GET directly.
+ * Use get_int(), get_str(), post_int() and post_str()     (from util.inc) to get POST and GET data.
+ * If a POST or GET value will be used in a SQL query,     use process_user_text() to escape it.
+