← Back to branch summary

~paulo-trezentos/apt/0.7.20_pbo

« back to all changes in this revision

Viewing changes to debian/libapt-pkg-doc/usr/share/doc/libapt-pkg-doc/style.txt

  • Committer: Paulo Trezentos
  • Date: 2010-07-19 00:47:36 UTC
  • Revision ID: paulo.trezentos@caixamagica.pt-20100719004736-e7gupo9ec0kpfx0s
Initial import

Show diffs side-by-side

added added

removed removed

Lines of Context:
debian/libapt-pkg-doc/usr/share/doc/libapt-pkg-doc/style.txt
 
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 seperators are intended to give
 
21
a visual seperate 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 transfering arrays/lists should probably return an iterator 
 
75
typedef or references..