Changes between Version 28 and Version 29 of CodingStyle
- Timestamp:
- Aug 30, 2016, 2:00:17 PM (8 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
CodingStyle
v28 v29 76 76 === Comments and #ifdefs === #comments 77 77 78 * Use `///` for all comments. The documentation is generated using Doxygen, so you should have a look at this example: 79 80 {{{ 81 /// Brief description for class test. 82 83 /// A more elaborate description for class test, 84 /// could be more than one line. 85 class Test 86 { 87 public: 88 89 /// A constructor. 90 91 /// A more elaborate description of the constructor. 92 Test(); 93 94 /// A destructor. 95 /// A more elaborate description of the destructor. 96 ~Test(); 97 98 /// a normal member taking two arguments and returning an integer value. 99 /// @param a an integer argument. 100 /// @param s a constant character pointer. 101 /// @see Test() 102 /// @see ~Test() 103 /// @see testMeToo() 104 /// @see publicVar() 105 /// @return The test results 106 int testMe(int a,const char *s); 107 108 /// A pure virtual member. 109 /// @see testMe() 110 /// @param c1 the first argument. 111 /// @param c2 the second argument. 112 virtual void testMeToo(char c1,char c2) = 0; 113 114 /// a public variable. 115 116 /// Details. 117 int publicVar; 118 119 /// a function variable. 120 121 /// Details. 122 int (*handler)(int a,int b); 123 }; 124 125 }}} 126 78 * Use `//` for all comments. 127 79 * Comment out blocks of code as follows: 128 80 {{{ … … 136 88 === Includes === #includes 137 89 138 * A `.cpp` file should have the minimum set of #includes to get that particular file to compile (e.g. the includes needed by `foo.cpp` should be in `foo.cpp`, not `foo.h`). 139 * `foo.cpp` should include `foo.h` first; after that, includes should be ordered from general (`<stdio.h>`) to specific (`shmem.h`). 90 * A `.cpp` file should have the minimum set of #includes to get that particular file to compile 91 (e.g. the includes needed by `foo.cpp` should be in `foo.cpp`, not `foo.h`). 92 * For readability, includes should be ordered from general (`<stdio.h>`) to specific (`foo.h`). 93 However, this order shouldn't matter. 140 94 141 95 === Extern declarations === #extern 142 96 143 * `foo.h` should have `extern` declarations for all public functions and variables in `foo.cpp` There should be no `extern` statements in `.cpp` files. 97 * `foo.h` should have `extern` declarations for all public functions and variables in `foo.cpp` 98 .There should be no `extern` statements in `.cpp` files. 144 99 145 100 === Use of static === #static … … 147 102 * If a function or variable is used in only one file, declare it `static`. 148 103 149 === Things to avoid unless there's a trulycompelling reason: === #try-avoid104 === Things to avoid unless there's a compelling reason: === #try-avoid 150 105 151 106 * Operator or function overloading. … … 155 110 156 111 * Use `typedef` (not `#define`) to define types. 157 * Don't use `memset()` or `memcpy()` to initialize or copy classes that are non-C compatible. Write a default constructor and a copy constructor instead. 112 * Don't use `memset()` or `memcpy()` to initialize or copy classes that are non-C compatible. 113 Write a default constructor and a copy constructor instead. 158 114 159 115 === Error codes === #error-codes 160 116 161 * (Almost) all functions should return an integer error code. Nonzero means error. See [source:boinc/lib/error_numbers.h lib/error_numbers.h] for a list of error codes. 162 * Calls to functions that return an error code should check the code. Generally they should return non-zero on error, e.g.: 117 * (Almost) all functions should return an integer error code. 118 Nonzero means error. See [source:boinc/lib/error_numbers.h lib/error_numbers.h] for a list of error codes. 119 * Calls to functions that return an error code should check the code. 120 Generally they should return non-zero on error, e.g.: 163 121 {{{ 164 122 retval = blah();
