akregator/HACKING

   1 ================================================================================
   2 Indentation
   3 ================================================================================
   4
   5 We use 4 spaces instead of tabs everywhere.
   6
   7 static void foo()
   8 {
   9     if(bar()) // <-- 4 spaces
  10         baz() // <-- 8 spaces
  11 }
  12
  13 ================================================================================
  14 Braces
  15 ================================================================================
  16
  17 Opening braces should always be on their own line.
  18
  19 class Foo
  20 {
  21     // stuff
  22 };
  23
  24 if (foo == bar)
  25 {
  26     // stuff
  27 }
  28
  29 while (foo == bar &&
  30        baz == quux &&
  31        flop == pop)
  32 {
  33     // stuff
  34 }
  35
  36 static void foo()
  37 {
  38     // stuff
  39 }
  40
  41 Exceptions include inline functions that are just returning or setting a
  42 value.  However multiple statements should not ever be combined onto one line:
  43
  44 class Foo
  45 {
  46     public:
  47         String value() const { return m_value; }
  48 };
  49
  50 Same goes for the main namespace of a header (the namespace where the class
  51 declaration is in, opposed to forward declaration (see also "Namespaces")
  52
  53 ================================================================================
  54 Spaces
  55 ================================================================================
  56
  57 Spaces should be used between the conditional / loop type and the
  58 conditional statement. They should not be used after parenthesis. However
  59 the should be to mark of mathematical or comparative operators.
  60
  61 if ( foo == bar )
  62     ^          ^
  63
  64 The marked spaces should be ommitted to produce:
  65
  66 if (foo == bar)
  67
  68 ================================================================================
  69 Header Organization
  70 ================================================================================
  71
  72 Guards:
  73
  74 For test.h, declaring the class Akregator::Test, use AKREGATOR_TEST_H, not TEST_H,
  75 nor _AKREGATOR_TEST_H_ etc. Comment the closing #endif.
  76
  77 #ifndef AKREGATOR_TEST_H
  78 #define AKREGATOR_TEST_H
  79 ...
  80 #endif // AKREGATOR_TEST_H
  81
  82 Member variables should always be private or protected and prefixed with "m_".
  83 Accessors may be inline in the headers. The organization of the members in a
  84 class should be roughly as follows:
  85
  86 public typedefs:
  87 public ctors/dtors:
  88 public methods:
  89 public slots:
  90 signals:
  91 protected methods:
  92 protected slots:
  93 protected fields:
  94 private ctors/dtors:
  95 private methods:
  96 private slots:
  97 private fields:
  98
  99
 100 If there are no private slots there is no need for two private sections, however
 101 private functions and private variables should be clearly separated.
 102
 103 The implementations files -- .cpp files -- should follow (when possible) the
 104 same order of function declarations as the header files.
 105
 106 Virtual functions should always be marked as such even in derived classes where
 107 it is not strictly necessary.
 108
 109 ================================================================================
 110 Namespaces
 111 ================================================================================
 112
 113 - Do not indent stuff in the "main namespace" of a file. But do for forward declarations.
 114 - comment the closing bracket of the namespace with // namespace Foo
 115
 116 Example:
 117
 118 namespace KParts
 119 {
 120     class ReadOnlyPart;
 121 }
 122 namespace Akregator {
 123
 124 class Foo
 125 {
 126 };
 127
 128 } // namespace Akregator
 129
 130 ================================================================================
 131 Whitespace
 132 ================================================================================
 133
 134 Whitespace should be used liberally.  When blocks of code are logically distinct
 135 I tend to put a blank line between them.  This is difficult to explain
 136 systematically but after looking a bit at the current code organization this
 137 ideally will be somewhat clear.
 138
 139 Also I tend to separate comments by blank lines on both sides.
 140
 141 ================================================================================
 142 Pointer and Reference Operators
 143 ================================================================================
 144
 145 Use "Foo* f" and "Foo& f" in function signatures and declarations. And also in
 146 signal/slot names.
 147
 148 ================================================================================
 149 Signals and Slots
 150 ================================================================================
 151
 152 Prefix slots/signals with "slot"/"signal". Fully qualify types used in arguments
 153 (i.e. add namespaces).
 154
 155 Example:
 156
 157 Use
 158
 159     signals:
 160
 161         signalFoo(const Akregator::Article&);
 162
 163 not
 164
 165     signals:
 166
 167         foo(const Article&);
 168
 169 ================================================================================
 170 Pointer and Reference Operators
 171 ================================================================================
 172
 173 An example object here:
 174
 175 test.h:
 176 #ifndef AKREGATOR_TEST_H
 177 #define AKREGATOR_TEST_H
 178
 179 #include "localinclude.h"
 180 #include "anotherlocalinclude.h"
 181 #include <kdeinclude1.h>
 182 #include <kdeinclude2.h>
 183 #include <qtinclude1.h>
 184 #include <qtinclude2.h>
 185
 186 class QSomething;
 187
 188 namespace Akregator {
 189
 190 class Test : public QObject
 191 {
 192     Q_OBJECT
 193
 194     public:
 195         typedef QValueList<Test> list;
 196
 197         Test();
 198         Test(QString someString);
 199         explicit Test(int i = 0);
 200
 201         virtual ~Test();
 202
 203         void someFunc();
 204         void someFunc2(QSomething *foo);
 205
 206         static Test *instance() { return m_instance; }
 207
 208     public slots:
 209         void receive(QSomething &);
 210
 211     signals:
 212         void send(QSomething &);
 213
 214     protected:
 215         void someProtectedFunc();
 216
 217         static void someProtectedStaticFunc();
 218
 219     protected slots:
 220         void protectedSlot();
 221
 222     protected:
 223         int m_protectedVar;
 224
 225     private:
 226         int privateMethod();
 227
 228         static int staticPrivateMethod();
 229
 230     private slots:
 231         void privateSlotIndeed(int youWonder);
 232
 233     private:
 234         int m_privateVar;
 235         QSomething* m_tastyThing;
 236
 237         static Test* m_instance;
 238 };
 239
 240 } // no ; after namespace (borks on gcc 3.4+)
 241
 242 #endif
 243
 244 test.cpp:
 245 #include "test.h"
 246 #include "localinclude.h"
 247 #include "anotherlocalinclude.h"
 248 #include <kdeinclude1.h>
 249 #include <kdeinclude2.h>
 250 #include <qtinclude1.h>
 251 #include <qtinclude2.h>
 252 #include <qsomething.h>
 253
 254 namespace Akregator {
 255
 256 Test::Test()
 257     : QObject()
 258     , m_protectedVar(0)
 259     , m_privateVar(0)
 260     , m_tastyThing(0)
 261     , m_instance(0)
 262 {
 263 }
 264
 265 Test::Test(QString someString)
 266     : QObject()
 267     , m_protectedVar(0)
 268     , m_privateVar(0)
 269     , m_tastyThing(someString)
 270     , m_instance(0)
 271 {
 272 }
 273
 274 Test::Test(int i);
 275     : QObject()
 276     , m_protectedVar(0)
 277     , m_privateVar(0)
 278     , m_tastyThing(i)
 279     , m_instance(0)
 280 {
 281     if (i == 0)
 282         kDebug() << "Zero initializer";
 283 }
 284
 285 } // namespace Akregator
 286
 287 ================================================================================
 288
 289 Original document by
 290 Scott Wheeler <wheeler@kde.org>
 291
 292 Amendments for Akregator needs by
 293 Stanislav Karchebny <stanislav.karchebny@kdemail.net>
 294 Frank Osterfeld <osterfeld@kde.org>