aboutsummaryrefslogtreecommitdiff log msg author committer range
 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184  .highlight .hll { background-color: #4f424c } .highlight { background: #2f1e2e; color: #e7e9db } .highlight .c { color: #776e71 } /* Comment */ .highlight .err { color: #ef6155 } /* Error */ .highlight .k { color: #815ba4 } /* Keyword */ .highlight .l { color: #f99b15 } /* Literal */ .highlight .n { color: #e7e9db } /* Name */ .highlight .o { color: #5bc4bf } /* Operator */ .highlight .p { color: #e7e9db } /* Punctuation */ .highlight .ch { color: #776e71 } /* Comment.Hashbang */ .highlight .cm { color: #776e71 } /* Comment.Multiline */ .highlight .cp { color: #776e71 } /* Comment.Preproc */ .highlight .cpf { color: #776e71 } /* Comment.PreprocFile */ .highlight .c1 { color: #776e71 } /* Comment.Single */ .highlight .cs { color: #776e71 } /* Comment.Special */ .highlight .gd { color: #ef6155 } /* Generic.Deleted */ .highlight .ge { font-style: italic } /* Generic.Emph */ .highlight .gh { color: #e7e9db; font-weight: bold } /* Generic.Heading */ .highlight .gi { color: #48b685 } /* Generic.Inserted */ .highlight .gp { color: #776e71; font-weight: bold } /* Generic.Prompt */ .highlight .gs { font-weight: bold } /* Generic.Strong */ .highlight .gu { color: #5bc4bf; font-weight: bold } /* Generic.Subheading */ .highlight .kc { color: #815ba4 } /* Keyword.Constant */ .highlight .kd { color: #815ba4 } /* Keyword.Declaration */ .highlight .kn { color: #5bc4bf } /* Keyword.Namespace */ .highlight .kp { color: #815ba4 } /* Keyword.Pseudo */ .highlight .kr { color: #815ba4 } /* Keyword.Reserved */ .highlight .kt { color: #fec418 } /* Keyword.Type */ .highlight .ld { color: #48b685 } /* Literal.Date */ .highlight .m { color: #f99b15 } /* Literal.Number */ .highlight .s { color: #48b685 } /* Literal.String */ .highlight .na { color: #06b6ef } /* Name.Attribute */ .highlight .nb { color: #e7e9db } /* Name.Builtin */ .highlight .nc { color: #fec418 } /* Name.Class */ .highlight .no { color: #ef6155 } /* Name.Constant */ .highlight .nd { color: #5bc4bf } /* Name.Decorator */ .highlight .ni { color: #e7e9db } /* Name.Entity */ .highlight .ne { color: #ef6155 } /* Name.Exception */ .highlight .nf { color: #06b6ef } /* Name.Function */ .highlight .nl { color: #e7e9db } /* Name.Label */ .highlight .nn { color: #fec418 } /* Name.Namespace */ .highlight .nx { color: #06b6ef } /* Name.Other */ .highlight .py { color: #e7e9db } /* Name.Property */ .highlight .nt { color: #5bc4bf } /* Name.Tag */ .highlight .nv { color: #ef6155 } /* Name.Variable */ .highlight .ow { color: #5bc4bf } /* Operator.Word */ .highlight .w { color: #e7e9db } /* Text.Whitespace */ .highlight .mb { color: #f99b15 } /* Literal.Number.Bin */ .highlight .mf { color: #f99b15 } /* Literal.Number.Float */ .highlight .mh { color: #f99b15 } /* Literal.Number.Hex */ .highlight .mi { color: #f99b15 } /* Literal.Number.Integer */ .highlight .mo { color: #f99b15 } /* Literal.Number.Oct */ .highlight .sa { color: #48b685 } /* Literal.String.Affix */ .highlight .sb { color: #48b685 } /* Literal.String.Backtick */ .highlight .sc { color: #e7e9db } /* Literal.String.Char */ .highlight .dl { color: #48b685 } /* Literal.String.Delimiter */ .highlight .sd { color: #776e71 } /* Literal.String.Doc */ .highlight .s2 { color: #48b685 } /* Literal.String.Double */ .highlight .se { color: #f99b15 } /* Literal.String.Escape */ .highlight .sh { color: #48b685 } /* Literal.String.Heredoc */ .highlight .si { color: #f99b15 } /* Literal.String.Interpol */ .highlight .sx { color: #48b685 } /* Literal.String.Other */ .highlight .sr { color: #48b685 } /* Literal.String.Regex */ .highlight .s1 { color: #48b685 } /* Literal.String.Single */ .highlight .ss { color: #48b685 } /* Literal.String.Symbol */ .highlight .bp { color: #e7e9db } /* Name.Builtin.Pseudo */ .highlight .fm { color: #06b6ef } /* Name.Function.Magic */ .highlight .vc { color: #ef6155 } /* Name.Variable.Class */ .highlight .vg { color: #ef6155 } /* Name.Variable.Global */ .highlight .vi { color: #ef6155 } /* Name.Variable.Instance */ .highlight .vm { color: #ef6155 } /* Name.Variable.Magic */ .highlight .il { color: #f99b15 } /* Literal.Number.Integer.Long *//* vim: set ft=cpp tw=80 sw=4 et : */ /** \page CodingStandards Coding Standards These are rough guidelines. You should stick to these unless there's a good reason to do otherwise. There are lots more standards that aren't documented here yet -- ask for clarification as necessary. \section CodingStandardsCopyrights Copyrights and Licence Paludis is licenced under the GPLv2. Any contributions must use this licence. You should copy the standard licence header from another source file when creating new source files. Copyright is handled on a per-file basis. If you are the primary author of a file, you should list yourself as the copyright holder. If you make a substantial contribution to a source file (for example, one or more non-trivial classes, functions or methods), you should add yourself as a copyright holder on that file. You should not add to the copyright for small changes or bug fixes. Copyright years are per contributor. See, for example, paludis/fs_entry.hh for a file that has multiple copyright holders with different years. Substantial contributors should also list themselves in the AUTHORS file. \section CodingStandardsIndentingAndSpacing Indenting and Spacing Indents are four spaces. There are no tabs anywhere. Braces go on a line of their own, and may be omitted if the clarity of the code isn't affected. Make sure you don't include trailing whitespace. Function calls have no space before or after the parentheses. Most operators and built-in functions have spaces before the opening parenthesis but not inside. The ! operator has a space after it. For example:: \code if (some_function("moo", 2)) do_stuff("moo"); else { // this needs some explanation while (end != do_other_stuff(foo) || ! foo) ++foo; } \endcode \section CodingStandardsSwitches Switches You'll sometimes see code like this: \code do { switch (my_enum) { case e_one: // ... continue; case e_two: // ... continue; } throw InternalError(PALUDIS_HERE, "Unexpected value for my_enum"); } while (false); \endcode The reason for using this rather than a default: label is that the compiler will (or at least the compiler we use will) generate a warning if someone later goes and adds e_three, and we haven't updated our switch to recognise it. \section CodingStandardsComments Comments All public and protected interfaces and classes should be documented in the header files via Doxygen. Implementations should be documented appropriately -- explain complicated or unobvious parts and anything that can easily be broken by other people. Don't bother with comments on obvious things. \section CodingStandardsNaming Naming Types are named in MixedCaseNoUnderscores. Variables and functions are named in lower_case_with_underscores. Private member variables that aren't going to end up being used anywhere external are _prefixed_with_underscore. Template values are suffixed_with_underscore_, and template typenames are SuffixedAsWell_ (and use typename rather than class, \ref EffCpp item 42). The files for SomeClass (and any small related utilities) would be some_class.hh and some_class.cc. We are somewhat inconsistent when it comes to what warrants its own file -- originally it was pretty much one class per file, but then compiles started taking too long so it's now more like one class plus related utilities and exceptions per file. Macros are PALUDIS_UPPER_CASE, but they're evil (\ref TCppPL section 7.8, \ref EffCpp item 2) so don't use them. Very short names for loop indices and the like are fine, but prefer longer, self-documenting names for proper variables. For loop iterator pairs, the usual style is: \code for (MyType::Iterator i(my_container.begin()), i_end(my_container.end()) ; i != i_end ; ++i) { // ... } \endcode If there's a convenient standard library algorithm available, use that instead of a manual loop (\ref EffSTL item 43). \section CodingStandardsPointers Pointers and References Try to avoid returning raw pointer types from raw interfaces, especially if the programmer is expected to deallocate them manually. Make liberal use of paludis::CountedPtr instead -- it's low overhead and a lot less prone to subtle screwups. See \ref EffCpp item 18. Pass object parameters by const reference rather than pointer to const unless you're prepared to accept a zero pointer. Avoid pass by value except for small integral types. See \ref EffCpp item 20. \section CodingStandardsNamespaces Namespaces Everything under paludis/ should be inside namespace paludis. Sometimes sub-namespaces are used where they look useful. \section CodingStandardsIncludeGuards Include Guards Include guards are \#define PALUDIS_GUARD_FILE_NAME_HH 1. \section CodingStandardsStandardLibrary Standard Library Never use using namespace std. It can bring arbitrary weirdness into the current namespace. It's ok to selectively introduce things from std where they're used a lot. See \ref TCppPL section 8.2.9.1. Make use of the standard library where suitable. It has fewer bugs than code you write yourself, and it may be doing clever optimisations behind the scenes. Remember the container member functions. Many containers have template constructors that take iterator pairs. Many containers have assign and swap methods. Use these over std::copy. See \ref EffSTL item 25. Don't use vector<bool>. It's just not worth it. See \ref EffSTL item 18. Although some compilers will let you get away with std::make_pair("foo", "bar"), some won't. Strictly speaking this violates the standard. Use std::make_pair(std::string("foo"), std::string("bar")) instead. \section CodingStandardsCasts Casts dynamic_cast is banned. It's slow (\ref EffCpp item 27) and a sign that you should be using one of visitors (\ref GoF Visitor), multiple dispatch (\ref MCppD chapter 11) or capability queries via a get_interface type method (for example, as described in \ref GoF Composite -- Implementation item 4) instead. reinterpret_cast is probably banned as well, unless we end up having to talk to some weirdly broken C libraries. There are very few legitimate uses for const_cast. It might be ok to use it as described in \ref EffCpp item 3. It might be ok to use it to talk to C libraries. There's nothing wrong with making appropriate use of static_cast. Old C style (Type) variable casts are banned. Function style casts (that is, Type(value)) should only be used when calling an explicit constructor to pass an object to a function. See \ref EffCpp item 27. */