| | 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 seperate 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 | transfered. 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 | transfered. Return by pointer should not be used unless ownership is |
| | 69 | transfered. |
| | 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.. |
projects / apt.git / blame_incremental