summaryrefslogtreecommitdiffstats
path: root/developer-doc/phb/coding.docbook
blob: 2bb791350f6c8a0e152f2e8f4aee278f9f759909 (plain)
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
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
<chapter id="coding-std">
<title>Coding Rules</title>
<para>
Where-ever possible this document should be referred to when questions
 regarding the format of the source code are raised. 
</para>

<para>
By the way, we know the code doesn't always conform to the standards at
the moment, but work is underway to change the code and all new code
submitted should conform to the standards.
</para>

<!-- SECTION =================================================== -->
<sect1 id="general">
<title>General</title>
<para>
The following list shows the general rules that should be regarded by any
developer working on &app;.
</para>

<itemizedlist>
<listitem>
<para>
Each file should contain only one declaration or implementation and the
filename should reflect the class name. e.g ksomethingdlg.h would contain a
declaration for the KSomethingDlg class.
</para>
</listitem>

<listitem>
<para>
A tab width of 2 spaces should be used and if your editor supports it, the
tabs should be changed into spaces. (KDevelop/KWrite supports tab
translation).
</para>
</listitem>

<listitem>
<para>
All dialogs should be located in the kmymoney2/dialogs directory.
</para>
</listitem>

<listitem>
<para>
Each class should be as self contained as possible. If for instance, you
are creating a dialog, then all the signals and slots should be connected
within that dialog class. Where access is needed to the class details
methods should be used. This enhances readability and makes maintenance a
lot easier with each object having it's own state, indentity and behaviour,
(see Object Oriented Analysis &amp; Design using UML, Bennet &amp; Co).
</para>
</listitem>

<listitem>
<para>
All user visible text should be wrapped in the i18n internationalisation
wrapper for translation.
</para>
</listitem>
</itemizedlist>

</sect1>


<!-- SECTION =================================================== -->
<sect1 id="header-files">
<title>Header Files</title>
<para>
The following rules apply to all header files.
</para>

<itemizedlist>
<listitem>
<para>
Header files shall end with the extension .h not .hpp.
</para>
</listitem>

<listitem>
<para>
All header files shall begin with a comment block as generated by KDevelop.
</para>
</listitem>

<listitem>
<para>
The remainder of the header file shall be surrounded by include stoppers.
The name of the macro used should be the capitalized filename with the dot
replaced by an underbar (e.g. KSettingsDlg.h --\> KSETTINGSDLG_H)
<example>
<title>Using include stoppers</title>
<screen>

  #ifndef KSETTINGSDLG_H
  #define KSETTINGSDLG_H
    /* remainder of header file */
  #endif // KSETTINGSDLG_H


</screen>
</example>

</para>
</listitem>

<listitem>
<para>
All classes designed for use by the KDE interface should begin with a 
<emphasis>K</emphasis>
with each separate word beginning with an uppercase letter e.g
KSomethingDlg.
</para>
</listitem>

<listitem>
<para>
The header file will include other header files in the following fashion
and same order:
</para>

<example>
<title>Including other header files</title>
<screen>

  //-----------------------------------------------------------------------
  // QT Headers
  #include &lt;qtlabel.h&gt;

  //-----------------------------------------------------------------------
  // KDE Headers
  #include &lt;kcombobox.h&gt;

  //-----------------------------------------------------------------------
  // Project Headers
  #include "mymoney/mymoneyfile.h"


</screen>
</example>
</listitem>

<listitem>
<para>
Each class should have a kdoc compatable comment header to describe the
class and it's function within kmymoney2.
</para>
</listitem>

<listitem>
<para>
Classes shall begin their declaration as such:
</para>

<example>
<title>Class declaration</title>
<screen>

  class KSomethingDlg : public KBaseClass {


</screen>
</example>

<para>
with an appopriate access declared.
</para>
</listitem>

<listitem>
<para>
Access modifiers should be left flushed in the class declaration with all
attributes and methods indented by one tab. The access methods will be in
order starting with private. The access identifier should exist even if no
attributes or methods exist. Only one identifier can exist of the same
type. 
</para>

<example>
<title>Complete class declaration</title>
<screen>

  class KSomethingDlg : public KBaseClass {
  private:
    TQString m_szSomeString;
    void useString(void);

  private slots:

  protected:

  protected slots:

  public:
    KSomethingDlg();

  public slots:

  signals:
  };


</screen>
</example>
</listitem>

<listitem>
<para>
All slot methods should begin with slot and signal methods should start with
signal. e.g 
</para>

<example>
<title>Declaration of slot and signal methods</title>
<screen>

  signalFoundTransaction();
  slotFoundTransaction();


</screen>
</example>
</listitem>

<listitem>
<para>
<anchor id="attribute-names"/>
Attribute names should begin with the m_ prefix to indicate that they are
member variables. The variable name should begin with a descriptive
identifier such as qcomboboxMethod. Explicit hungarian notation is also
fine. Examples of valid variable names can be found below:
</para>

<example>
<title>Attribute naming convention</title>
<screen>

  QComboBox m_qcomboboxMethod;
  int m_intCounter;
  int m_nCounter;


</screen>
</example>
</listitem>

<listitem>
<para>
Method names should specify a return and argument(s) unless used in a slot
or signal where the argument list can be left blank if necessary. The
method should start with a lower case letter with each subsequent word
having an upper case start letter.
</para>
</listitem>
</itemizedlist>

</sect1>

<!-- SECTION =================================================== -->
<sect1 id="source-files">
<title>Source Files</title>
<para>
The following rules apply to all source code files.
</para>

<itemizedlist>
<listitem>
<para>
C++ source files shall end with the extension .cpp not .cc or .cxx
</para>
</listitem>

<listitem>
<para>
As with header files these should start with a header block similar to the
one generated by KDevelop.
</para>
</listitem>

<listitem>
<para>
Include files shall be included in the same format as for header file e.g 
</para>

<example>
<title>Including header files in source files</title>
<screen>
  //-----------------------------------------------------------------------
  // QT Headers
  #include &lt;qtlabel.h&gt;

  //-----------------------------------------------------------------------
  // KDE Headers
  #include &lt;kcombobox.h&gt;

  //-----------------------------------------------------------------------
  // Project Headers
  #include "mymoney/mymoneyfile.h"
  #include "ksomethingdlg.h"


</screen>
</example>
</listitem>

<listitem>
<para>
Methods should be implemented as such:
</para>

<example>
<title>Method implementation</title>
<screen>

  void KSomethingDlg::useString(void)
  {
    .. function body
  }


</screen>
</example>

<para>
with the function body indented by one tab (equals two spaces).
</para>
</listitem>

<listitem>
<para>
Flow control statements should preferably follow the Kernighan &amp; Ritchie
style as such:
</para>

<example>
<title>Kernighan &amp; Ritchie flow control style</title>
<screen>

  while (something_is_true) {
    operate on something;
  }


</screen>
</example>

<para>
although the following Allman style is acceptable:
</para>

<example>
<title>Allman flow control style</title>
<screen>

  while (something_is_true)
  {
    operate on something;
  }


</screen>
</example>

<para>
It is also acceptable for one line body statements to omit the curly braces
as such: 
</para>

<example>
<title>One line body flow control style</title>
<screen>

  while (something_is_true)
    operate;


</screen>
</example>
</listitem>

<listitem>
<para>
Local variables should not be prefixed by the m_ member prefix and should
start with a prefix as discussed for the
<link linkend="attribute-names">header file</link>.
For example:
</para>

<example>
<title>Local variable nameing convention</title>
<screen>

  TQString qstringTemp;
  char *pszTemp;


</screen>
</example>
</listitem>

<listitem>
<para>
Each method should have a comment block preceeding it in a suitable format
for other developers to see how the method works and what types of return
and arguments it expects. It does not have to be kdoc compatable because
kdoc only parses the header files. All kdoc comment blocks should be in the
header files.
</para>
</listitem>
</itemizedlist>
</sect1>
</chapter>