File: CODING_GUIDELINES.dox

package info (click to toggle)
kodi 2:17.6+dfsg1-4
  • links: PTS, VCS
  • area: main
  • in suites: buster, sid
  • size: 87,148 kB
  • sloc: cpp: 588,459; xml: 58,591; ansic: 42,735; sh: 12,932; makefile: 4,785; python: 2,803; objc: 1,075; perl: 1,041; cs: 624; java: 500; asm: 294; sed: 16
file content (372 lines) | stat: -rw-r--r-- 9,281 bytes parent folder | download | duplicates (3)
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
/*!

\page code_guidelines Code guidelines and formatting conventions

@brief \doc_header{ Code guidelines and formatting conventions }

\tableofcontents

These are conventions which we try to follow when writing code for Kodi. They
are this way mainly for reasons of taste, however, sticking to a common set of
formatting rules also makes it slightly easier to read through our sources. If
you want to submit patches, please try to follow these rules.

As such we don't follow these rules slavishly, in certain cases it is ok (and
in fact favorable) to stray from them.

================================================================================
\section code_guidelines_1 Indentation

Use spaces as tab policy with an indentation size of 2

--------------------------------------------------------------------------------
\subsection code_guidelines_1_1 Statements

No multiple statements on a single line, like this:
~~~~~~~~~~~~~
std::vector<std::string> test; test.push_back("foobar"); // This is the bad way
~~~~~~~~~~~~~

Always use a new line for a new statement:
~~~~~~~~~~~~~
std::vector<std::string> test;
test.push_back("foobar");
~~~~~~~~~~~~~

With them becomes it much more easy for debugging of faults to see direct on the
line what has created the fault.


--------------------------------------------------------------------------------
\subsection code_guidelines_1_2 Namespaces

Namespaces are not required to use any indentation to simplify nested namespaces
and wrapping `.cpp` files in a namespace

~~~~~~~~~~~~~
namespace KODI
{
namespace UTILS
{
class ILogger
{
  void Log(...) = 0;
}
}
}
~~~~~~~~~~~~~

\subsection code_guidelines_1_3 Headers

Included header files `*.h`, are to sort alphabetical to prevent double used file
definition and allow better overview

- On cpp define used header first to confirm needed headers are present on them itself
- As next use the global system headers e.g. `<cassert>` or `"system.h"`
- Then insert all the headers needed for the file itself

~~~~~~~~~~~~~
#include "PVRManager.h"

#include <cassert>
#include <utility>

#include "Application.h"
#include "Util.h"
#include "addons/AddonInstaller.h"
#include "dialogs/GUIDialogExtendedProgressBar.h"
#include "messaging/helpers/DialogHelper.h"
#include "music/tags/MusicInfoTag.h"
#include "network/Network.h"
#include "pvr/addons/PVRClients.h"
#include "pvr/channels/PVRChannel.h"
#include "settings/Settings.h"
#include "threads/SingleLock.h"
#include "utils/JobManager.h"
#include "utils/log.h"
#include "utils/Variant.h"
#include "video/VideoDatabase.h"
~~~~~~~~~~~~~

================================================================================
\section code_guidelines_2 Braces

Braces should go to newline and your code should look like the following example:

~~~~~~~~~~~~~
if (int i = 0; i < t; i++)
{
  [...]
}
else
{
  [...]
}

class Dummy()
{
  [...]
}
~~~~~~~~~~~~~

================================================================================
\section code_guidelines_3 Whitespaces

Conventional operators should be surrounded by a whitespace.

~~~~~~~~~~~~~
a = (b + c) * d;
~~~~~~~~~~~~~

Reserved words should be separated from opening parentheses by a whitespace.

~~~~~~~~~~~~~
while (true)
for (int i = 0; i < x; ++i)
~~~~~~~~~~~~~

Commas should be followed by a whitespace.

~~~~~~~~~~~~~
void Dummy::Method(int a, int b, int c);
int d, e;
~~~~~~~~~~~~~

Semicolons should be followed by a whitespace if there is more than one
expression per line.

~~~~~~~~~~~~~
for (int i = 0; i < x; ++i)
doSomething(e); doSomething(f); // this is probably bad style anyway
~~~~~~~~~~~~~

--------------------------------------------------------------------------------
\subsection code_guidelines_3_1 No vertical alignment

Do not use whitespaces to align value names together, this becomes problematic
on updates to see the change, if the whitspaces need to change on all.

This should be not used:
~~~~~~~~~~~~~
...

int                  value1             = 0;
int                  value2             = 0;
CExampleClass       *exampleClass       = nullptr;
CBiggerExampleClass *biggerExampleClass = nullptr;

exampleClass       = new CExampleClass      (value1, value2);
biggerExampleClass = new CBiggerExampleClass(value1, value2);

exampleClass      ->InitExample();
biggerExampleClass->InitExample();

...
~~~~~~~~~~~~~

Use it as:
~~~~~~~~~~~~~
...

int value1 = 0;
int value2 = 0;
CExampleClass *exampleClass = nullptr;
CBiggerExampleClass *biggerExampleClass = nullptr;

exampleClass = new CExampleClass(value1, value2);
biggerExampleClass = new CBiggerExampleClass(value1, value2);

exampleClass->InitExample();
biggerExampleClass->InitExample();

...
~~~~~~~~~~~~~

================================================================================
\section code_guidelines_4 Control statements

Insert new line before

- else in an if statement
- catch in a try statement
- while in a do statement


--------------------------------------------------------------------------------
\subsection code_guidelines_4_1 if else

- put then statement, return or throw to new line
- keep else if on one line 

~~~~~~~~~~~~~
if (true)
  return;

if (true)
{
  [...]
} 
else if (false)
{
  return;
} 
else
  return;
~~~~~~~~~~~~~

--------------------------------------------------------------------------------
\subsection code_guidelines_4_2 switch / case

~~~~~~~~~~~~~[.cpp}
switch (cmd)
{
  case x:
  {
    doSomething();
    break;
  }
  case x:
  case z:
    return true;
  default:
    doSomething();
}
~~~~~~~~~~~~~

================================================================================
\section code_guidelines_5 Naming
\subsection code_guidelines_5_1 Namespaces

Namespaces should be in uppercase letters

~~~~~~~~~~~~~
namespace KODI
{
...
}
~~~~~~~~~~~~~

\subsection code_guidelines_5_2 Constants

Use upper case with underscore spacing where necessary.

~~~~~~~~~~~~~
const int MY_CONSTANT = 1;
~~~~~~~~~~~~~

--------------------------------------------------------------------------------
\subsection code_guidelines_5_3 Enums

Use CamelCase for the enum name and upper case for the values.

~~~~~~~~~~~~~
enum Dummy
{
  VALUE_X,
  VALUE_Y
};
~~~~~~~~~~~~~

--------------------------------------------------------------------------------
\subsection code_guidelines_5_4 Interfaces

We use CamelCase for interface names and they should be prefixed with an
uppercase I. Filename should match the interface name, e.g. `ILogger.h`

~~~~~~~~~~~~~
class ILogger
{
  void Log(...) = 0;
}
~~~~~~~~~~~~~

--------------------------------------------------------------------------------
\subsection code_guidelines_5_5 Classes

We use CamelCase for class names and they should be prefixed with an uppercase C.
Filename should match the class name without the prefixed C, e.g. `Logger.cpp`

~~~~~~~~~~~~~
class CLogger : public ILogger
{
  void Log(...)
}
~~~~~~~~~~~~~

--------------------------------------------------------------------------------
\subsection code_guidelines_5_6 Methods

We use CamelCase for method names and first letter should always be upper case.
Even if the methods are private or protected.

~~~~~~~~~~~~~
void MyDummyClass::DoSomething();
~~~~~~~~~~~~~

--------------------------------------------------------------------------------
\subsection code_guidelines_5_7 Variables

We use CamelCase for variables. Type prefixing is optional.
\subsubsection code_guidelines_5_7_1 Global Variables

Prefix global variables with g_

~~~~~~~~~~~~~
int g_globalVariableA;
~~~~~~~~~~~~~

\warning Use of globals reduces the chance of submitted code to be accepted to a minimum

\subsubsection code_guidelines_5_7_2 Member Variables

Prefix member variables with m_

~~~~~~~~~~~~~
int m_variableA;
~~~~~~~~~~~~~

================================================================================
\section code_guidelines_6 Conventions

--------------------------------------------------------------------------------
\subsection code_guidelines_6_1 Casts

New code should use C++ style casts and not older C style casts. When modifying
existing code the developer can choose to update it to C++ style casts or leave
as is. Remember that whenever a dynamic_cast is used the result can be a nullptr
and needs to be checked accordingly.

--------------------------------------------------------------------------------
\subsection code_guidelines_6_2 NULL vs nullptr

Prefer the use of nullptr instead of NULL. nullptr is a typesafe version and as
such can't be implicitly converted to int or anything else.

--------------------------------------------------------------------------------
\subsection code_guidelines_6_3 auto

Feel free to use auto wherever it improves readability. Good places are
iterators or when dealing with containers.

~~~~~~~~~~~~~
std::map<std::string, std::vector<int>>::iterator i = var.begin();
vs
auto i = var.being();
~~~~~~~~~~~~~

--------------------------------------------------------------------------------
\subsection code_guidelines_6_4 for loops

Use newer style foreach loops whenever it makes sense. If iterators are used see
above about using auto.

~~~~~~~~~~~~~
for (auto& : var)
{
  ...
}
~~~~~~~~~~~~~

Use const auto& if there's no reason to modify the value.

*/