"Fossies" - the Fresh Open Source Software Archive

Member "xorp/devnotes/coding-style.txt" (19 Jul 2010, 7110 Bytes) of package /linux/misc/xorp-1.8.5-src.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 #
    2 # $XORP: xorp/devnotes/coding-style.txt,v 1.6 2007/05/23 12:12:33 pavlin Exp $
    3 #
    4 
    5 	Provisional XORP C++ coding style
    6 
    7 This is a *provisional* attempt to lay down some rules that we can
    8 adhere to and moan about. The style is only intended to apply to new
    9 code, not code that we import.  Hopefully, the style is equidistant
   10 from our default coding styles that all are equally peturbed.
   11 
   12 - DOCTRINE
   13 
   14   Ignore any section of this document when doing so would enhance
   15   readability.  Feel free to edit someone else's code into agreement
   16   with these principles, or into agreement with your own variant of
   17   these principles.  Expect that your code may be likewise edited.
   18 
   19 - FILE PROLOGUES
   20 
   21   Files should have a prologue containing the copyright, a description
   22   of what the file does, an RCS version id, and an RCS
   23   string/identifier in implementation files that ident(1) can use.
   24 
   25   We have a standard templates to work from:
   26      devnotes/template.hh
   27      devnotes/template.cc
   28      devnotes/template.h
   29      devnotes/template.c
   30 
   31 - INDENTATION
   32 
   33   Use 4 spaces per indent level.  Indentation should generally follow
   34   "gnu".  The default emacs c/c++ style is gnu, can be set with
   35   M-x c-set-style gnu).
   36 
   37 - BRACES
   38 
   39   Try to avoid gratuitous newlines between statements opening a brace
   40   and the opening brace. E.g., prefer:
   41 
   42 	if (abc == 3) {
   43 		/* XXX */
   44 	}
   45 
   46   to:
   47 	if (abc == 3)
   48 	{
   49 		/* XXX */
   50 	}
   51 
   52   For the sake of readability, try to place white space either side of
   53   braces. E.g., prefer:
   54 	bool foo() { return _some_value; }
   55   to:
   56 	bool foo() {return some_value;}
   57 
   58 - REFERENCE AND POINTER ANNOTATIONS
   59 
   60   Prefer:
   61 	foo(int& x) and bar(int* y)
   62   to:
   63 	foo(int &x) and bar(int *y)
   64 
   65   The former appears to be more widely used in C++ literature and so we go
   66   with this for the sake of consistency.
   67 
   68 - TEMPORARY REFERENCES
   69 
   70   Temporary references can help make code more readable.  When used
   71   with containers to pointer types the resulting code can be more
   72   readable and efficient.
   73 
   74 	static void process(const string& s);	    // Forward declaration
   75 
   76 	static void
   77 	process_long_names1(list<string*> names)
   78 	{
   79 	    list<string*>::const_iterator ci;
   80 	    for (ci = names.begin(); ci != names.end(); ++ci) {
   81 	        if ((*ci)->size() > 10) {	    // Direct use of iterator
   82 		    process(*(*ci));
   83 		}
   84 	    }
   85 	}
   86 
   87 	static void
   88 	process_long_names2(list<string*> names)
   89 	{
   90 	    list<string*>::const_iterator ci;
   91 	    for (ci = names.begin(); ci != names.end(); ++ci) {
   92 		const string& s = *(*ci);	    // Use of temporary ref
   93 		if (s.size() > 10) {
   94 		    process(s);
   95 		}
   96 	    }
   97 	}
   98 
   99 - COMMENTS
  100 
  101   Use // for comments.
  102 
  103   Avoid obvious comments inside routines. Any comments inside routines
  104   should be short -- one line, when possible. Prefer single blank
  105   lines for separating sections of code.
  106 
  107 - API DOCUMENTATION (kdoc)
  108 
  109   All major routines should have a comment briefly describing what
  110   they do.  We use kdoc comments (similar to javadoc) to generate API
  111   overviews and programming documentation.
  112 
  113 - TERMINAL WIDTH
  114 
  115   Assume the terminal is 80 characters wide.  Sure there'll be odd
  116   times when wraps cannot be avoided, but gratuitous wrapping will
  117   give you a "wide boy" reputation.
  118 
  119 - CAPITALIZATION
  120 
  121 	class Wrench {
  122 	public:
  123 	    Wrench() { ... };
  124 	    ~Wrench() { ... };
  125 	    apply_force();
  126 	    ...
  127 	private:
  128 	    double _weight;
  129 	};
  130 
  131   Note that the class's public interface comes first.
  132 
  133 - UNDERSCORING
  134 
  135   Member variables should begin with an underscore.  Regular variables
  136   and function names should separate words with underscores.
  137 
  138   Double underscores should never be used, they are often used by the
  139   compiler during name munging.
  140 
  141 - NAMES FOR MODIFIERS AND ACCESSORS.
  142 
  143   Often, a private member variable will have associated public member
  144   functions that get and/or set its value. If the variable is named
  145   "_xxx", name the getter function "xxx()" and the setter function
  146   "set_xxx()". The getter function should generally be const.
  147 
  148 - STRING METHODS
  149 
  150   When necesary to have a string method, call it str().  In general, try
  151   to avoid adding operator string().
  152 
  153 - BOOL METHODS
  154 
  155   In general, always avoid adding operator bool(), unless there is a
  156   strong reason for adding it.
  157 
  158 - METHOD DEFINITIONS
  159 
  160   When defining C++ in implementation files place the return value
  161   and class/method declarations on separate lines. E.g.,
  162 
  163 	const char*
  164 	LuckyEightBall::speak() const
  165 	{
  166 	// blah blah
  167 	}
  168 
  169 - ABBREVIATIONS
  170 
  171   Should be avoided, especially in method names.
  172 
  173 - INTEGER TYPES
  174 
  175   Use integer types defined in inttypes.h, these are POSIX compatible
  176   and portable.
  177 
  178 - USE OF CONST
  179 
  180   Decorate member functions with "const" whenever appropriate for
  181   purposes of documentation. Member functions that do not alter an
  182   object's value should be "const". Sometimes, a member variable is
  183   altered by a function that does not conceptually change the object's
  184   value. Mark such member variables as "mutable" to enhance the
  185   applicability of "const".
  186 
  187 - USE OF EXCEPTIONS AND STANDARD TEMPLATE LIBRARY
  188 
  189   Non-kernel modules should use exceptions and the standard template
  190   library where appropriate.
  191 
  192 - USE OF AUTOCONF
  193 
  194   We will use GNU autoconf to improve portability. The "xorp_config.h"
  195   header file will define symbols specifying system properties that
  196   may differ between reasonable Unices. This file is included by
  197   "libxorp/xorp.h" which itself includes and defines a number of other
  198   useful header files and features. The first file included by any XORP
  199   source file should be "libxorp/xorp.h".
  200   However, if one of the included header files is the module-specific
  201   "foo_module.h" (required by "libxorp/xlog.h"), that file should
  202   be included before "libxorp/xorp.h".
  203 
  204 - INCLUDE FILES
  205 
  206   Include files should be sorted into domain, each domain separated by
  207   a blank line:
  208 
  209 	"foo_module.h"
  210 	"libxorp/xorp.h"
  211 	kernel includes
  212 	sys includes
  213 	net includes
  214 	default include path includes
  215 	XORP libraries includes
  216 	local includes
  217 
  218   Don't sweat it too hard, however.
  219 
  220 - SPACES AND PARENTHESES
  221 
  222   Binary operators should have spaces around them to ease
  223   decipherment.  Parentheses have to used when precedence dictates and
  224   can be used to reduce confusion, particularly with long
  225   expressions. Do not put spaces around parentheses.
  226 
  227   Keywords should likewise have spaces around them.  For example,
  228   `if (x)', not `if(x)'; and `return x', not `return(x)'.
  229 
  230 - VARIABLE DECLARATIONS
  231 
  232   Place variable declarations at the beginning of the relevant
  233   scope. This includes placing declarations in the middle of
  234   functions, close to their first uses, when appropriate. Declare
  235   iteration variables inside the `for' statement when possible; this
  236   is most of the time. Declare a test variable inside the `if' test
  237   when possible; this happens comparatively rarely. Prefer multiple
  238   declarations when defining several variables that require
  239   initializers.
  240 
  241 - PORTABILITY
  242 
  243   All IPv6-specific code should be "#ifdef HAVE_IPV6" :
  244   #ifdef HAVE_IPV6
  245 	 ....
  246   #endif // HAVE_IPV6
  247 
  248   If there is only one line of code between #ifdef and #endif, then
  249   do not add the comment after "#endif".
  250