| 1 | Acronyms |
| 2 | ~~~~~~~~ |
| 3 | * dpkg is a 'word' the first d may be upper case - Dpkg |
| 4 | * APT is a proper Acronym, all upper case please. |
| 5 | |
| 6 | Pkg - A Package |
| 7 | Ver - A version |
| 8 | |
| 9 | Indenting, Comments, Etc |
| 10 | ~~~~~~~~~~~~~~~~~~~~~~~~ |
| 11 | Would make Linus cry :P However it is what I prefer. 3 space indent, |
| 12 | 8 space tab all braces on separate lines, function return on the same line |
| 13 | as the function, cases aligned with their code. The 'indent' options for |
| 14 | this style are: |
| 15 | indent -bl -bli0 -di1 -i3 -nsc -ts8 -npcs -npsl |
| 16 | |
| 17 | Each file gets a block at the top that should describe what the file does, |
| 18 | basically a summary of purpose along with any special notes and |
| 19 | attributions. The }}} and {{{ are folding marks if you have a folding |
| 20 | editor such as jed, the function separators are intended to give |
| 21 | a visual separate between functions for easier browsing of the larger files, |
| 22 | or indexed folding if you have such an editor. |
| 23 | |
| 24 | Each file should have 1 or 0 primary include files, that include |
| 25 | file must always be the first include file included by the .cc. G++ |
| 26 | #pragma interface/implementation is used, as well as anti-include-twice |
| 27 | #ifdefs. |
| 28 | |
| 29 | Include files, since there are so many, get their own subdirectory off |
| 30 | the include search path, this is used consistently throughout all the code. |
| 31 | #include "" should never be used for a global exported header file, only |
| 32 | local ones. |
| 33 | |
| 34 | C++ Features |
| 35 | ~~~~~~~~~~~~ |
| 36 | Due to the legacy compiler heritage, exceptions, RTTI and name spaces are |
| 37 | not used. Templates are used *sparingly* since G++ has traditionally had |
| 38 | very weak support for them, this includes STL templates. |
| 39 | |
| 40 | Namespaces will probably be put in the code sometime after G++ 3, which will |
| 41 | be a huge re-org again to make sanity, the majority of all nested things |
| 42 | will go away. |
| 43 | |
| 44 | The C++ standard library's non parameterized types (string is included in |
| 45 | this) are used freely when appropriate. |
| 46 | |
| 47 | The new C++ #include <iostream> (note the lack of a .h) is used for the |
| 48 | standard library, but not for my code. |
| 49 | |
| 50 | Arguments and Ownership |
| 51 | ~~~~~~~~~~~~~~~~~~~~~~~ |
| 52 | [much of the code follows this now] |
| 53 | These guidlines should be followed except in two cases.. the first |
| 54 | is where it makes no sense, such as in a casting operator and the second is to |
| 55 | retain API compatibility (this should be rare, since a change in the input |
| 56 | almost always designates a change in ownership rules). |
| 57 | |
| 58 | * Pass by value or pass by reference should borrow the object from the |
| 59 | caller |
| 60 | * Pass by non-const reference may be used to indicate a OUT type variable |
| 61 | * Pass by pointer (except in the case where the pointer is really an array) |
| 62 | should be used when the object will be retained or ownership will be |
| 63 | transferred. Ownership transference should be rare and noted by a comment. |
| 64 | * Standard C things (FILE * etc) should be left as is. |
| 65 | |
| 66 | * Return by references should indicate a borrowed object |
| 67 | * Return by pointer (except arrays) should indicate ownership is |
| 68 | transferred. Return by pointer should not be used unless ownership is |
| 69 | transferred. |
| 70 | * Return by pointer to variable indicates ownership transfer unless the |
| 71 | pointer is an 'input' parameter (designated generally by an =0, |
| 72 | indicating a default of 'none') |
| 73 | |
| 74 | Non-ownership transferring arrays/lists should probably return an iterator |
| 75 | typedef or references.. |