"Fossies" - the Fresh Open Source Software Archive

Member "apt-1.9.4/doc/style.txt" (19 Sep 2019, 3282 Bytes) of package /linux/misc/apt-1.9.4.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 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 guidelines 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..