path: root/docs/doxygen/CODING_GUIDELINES.dox

/*!

\page code_guidelines Code guidelines and formatting conventions

@brief \doc_header{ Code guidelines and formatting conventions }

\tableofcontents

When working in a large group, the two most important values are readability
and maintainability. We code for other people, not computers. To accomplish
these goals, we have created a unified set of code conventions.

Conventions can be bent or broken in the interest of making code more readable
and maintainable. However, if you submit a patch that contains excessive style
conflicts, you may be asked to improve your code before your pull request is
reviewed.

================================================================================
\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 have to be sorted alphabetically to prevent duplicates and
allow better overview, with an empty line clearly separating sections.

Header order has to be:

- Own header file
- Other Kodi includes
- C and C++ system files
- Other libraries' header files

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

#include "addons/AddonInstaller.h"
#include "dialogs/GUIDialogExtendedProgressBar.h"
#include "messaging/helpers/DialogHelper.h"
#include "messaging/ApplicationMessenger.h"
#include "messaging/ThreadMessage.h"
#include "music/tags/MusicInfoTag.h"
#include "music/MusicDatabase.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"
#include "Application.h"
#include "ServiceBroker.h"

#include <cassert>
#include <utility>

#include <libavutil/pixfmt.h>
~~~~~~~~~~~~~

Place directories before files. If the headers aren't sorted, either do your best
to match the existing order, or precede your commit with an alphabetization commit.

If possible, avoid including headers in another header. Instead, you can
forward-declare the class and use a `std::unique_ptr`:

~~~~~~~~~~~~~
class CFileItem;

class Example
{
  ...
  std::unique_ptr<CFileItem> m_fileItem;
}
~~~~~~~~~~~~~

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

Braces have to go to a new line.

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

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

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

Conventional operators have to be surrounded by a whitespace.

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

Reserved words have to be separated from opening parentheses by a whitespace.

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

Commas have to be followed by a whitespace.

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

Semicolons have to be followed by a newline.

~~~~~~~~~~~~~
for (int i = 0; i < x; ++i)
doSomething(e);
doSomething(f);
~~~~~~~~~~~~~

Initializer lists have spaces between elements, but no surrounding spaces.

~~~~~~~~~~~~~
const char *aStringArray[] = {"one", "two", "three"};
~~~~~~~~~~~~~

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

Do not use whitespaces to align value names together. This causes problems
on code review if one needs to realign all values to their new position.

Wrong:
~~~~~~~~~~~~~
...

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();

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

Right:
~~~~~~~~~~~~~
...

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

~~~~~~~~~~~~~
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 have to be in uppercase.

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

\subsection code_guidelines_5_2 Constants

Use uppercase with underscore spacing where necessary.

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

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

Use CamelCase for the enum name and uppercase for the values.

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

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

Use CamelCase for interface names and they have to be prefixed with an
uppercase I. Filename has to 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 have to be prefixed with an uppercase C.
Filenamehas match the class name without the prefixed C, e.g. `Logger.cpp`

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

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

Use CamelCase for method names and first letter shas to be uppercase.
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 has to 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.

--------------------------------------------------------------------------------
\subsection code_guidelines_6_5 default member initialization

Use default member initialization instead of initializer lists or constructor assignments whenever it makes sense.
~~~~~~~~~~~~~
class Foo
{
  bool bar = false;
};
~~~~~~~~~~~~~

*/