Skip to content

Latest commit

 

History

History
361 lines (309 loc) · 9.02 KB

CODE_GUIDELINES.md

File metadata and controls

361 lines (309 loc) · 9.02 KB
Raw

Kodi Logo

Code Guidelines

Table of Contents

  1. Motivation
  2. Document Conventions
  3. Indentation
  4. Statements
  5. Namespaces
  6. Headers
  7. Braces
  8. Whitespace
  9. Vertical Alignment
  10. Controls Statements
    10.1. if else
    10.2. switch case
  11. Naming
    11.1. Namespaces
    11.2. Constants
    11.3. Enums
    11.4. Interfaces
    11.5. Classes
    11.6. Methods
    11.7. Variables
  12. Conventions
    12.1. Casts
    12.2. NULL vs nullptr
    12.3. auto
    12.4. for loops
    12.5. Default member initialization

1. Motivation

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.

2. Document Conventions

Several different strategies are used to draw your attention to certain pieces of information. In order of how critical the information is, these items are marked as a note, tip, or warning. For example:

NOTE: Linux is user friendly... It's just very particular about who its friends are.
TIP: Algorithm is what developers call code they do not want to explain.
WARNING: Developers don't change light bulbs. It's a hardware problem.

back to top

3. Indentation

Use spaces as tab policy with an indentation size of 2.

back to top

4. Statements

No multiple statements on a single line.

std::vector<std::string> test; test.push_back("foobar");

Always use a new line for a new statement.

std::vector<std::string> test;
test.push_back("foobar");

It is much easier to debug if one can pinpoint a precise line number.

back to top

5. Namespaces

Indentation is not required to simplify nested namespaces and wrapping .cpp files in a namespace.

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

back to top

6. 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;
}

back to top

7. Braces

Braces have to go to a new line.

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

back to top

8. Whitespace

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"};

back to top

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

back to top

10. Controls Statements

Insert a new line before every:

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

10.1. if else

Put then, return or throw statements on a new line. Keep else if statements on one line.

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

10.2. switch case

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

back to top

11. Naming

11.1. Namespaces

Namespaces have to be in uppercase.

namespace KODI
{
  [...]
}

11.2. Constants

Use uppercase with underscore spacing where necessary.

const int MY_CONSTANT = 1;

11.3. Enums

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

enum Dummy
{
  VALUE_X,
  VALUE_Y
};

11.4. Interfaces

Use CamelCase for interface names and they have to be prefixed with an uppercase I. Filename has to match the interface name without the prefixed I, e.g. Logger.h

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

11.5. Classes

Use CamelCase for class names and they have to be prefixed with an uppercase C. Filename has to match the class name without the prefixed C, e.g. Logger.cpp

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

11.6. Methods

Use CamelCase for method names and first letter has to be uppercase, even if the methods are private or protected.

void MyDummyClass::DoSomething();

11.7. Variables

Use CamelCase for variables. Type prefixing is discouraged.

Global Variables

Prefix global variables with g_

int g_globalVariableA;

WARNING: Avoid globals use. It increases the chances of submitted code to be rejected.

Member Variables

Prefix member variables with m_

int m_variableA;

back to top

12. Conventions

12.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 on a pointer object the result can be a nullptr and needs to be checked accordingly.

12.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.

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

12.4. for loops

Use range-based for loops wherever it makes sense. If iterators are used see above about using auto.

for (const auto& : var)
{
  [...]
}

Remove const if the value has to be modified.

12.5. Default member initialization

Use default member initialization instead of initializer lists or constructor assignments whenever it makes sense.

class Foo
{
  bool bar = false;
};

back to top