git.sesse.net Git - kdenlive/blob - HACKING

   1
   2 This is the coding guideline for Kdenlive.
   3
   4 Committing
   5     Auto-indent
   6         Please don't use for existing files. It is very likely to break manual tweaks like:
   7             const int componentFlags =   (ui->cbY->isChecked() ? 1 : 0) * HistogramGenerator::ComponentY
   8                                        | (ui->cbS->isChecked() ? 1 : 0) * HistogramGenerator::ComponentSum
   9                                        | (ui->cbR->isChecked() ? 1 : 0) * HistogramGenerator::ComponentR
  10                                        | (ui->cbG->isChecked() ? 1 : 0) * HistogramGenerator::ComponentG
  11                                        | (ui->cbB->isChecked() ? 1 : 0) * HistogramGenerator::ComponentB;
  12         which are intended to improve readability.
  13
  14     Changelog
  15         When adding a new feature, add it to the CHANGELOG file. Features often are not mentioned
  16         in the bug tracker; adding it to the changelog helps keeping track of them.
  17
  18     Bug fixes
  19         Bugs often are in mantis. When fixing a bug, add a link to the bug tracker entry in the commit log
  20         and close the bug there.
  21         If the bug is not in mantis, it should be (a) added (and marked as fixed) if it is an important bug,
  22         or (b) not added otherwise.
  23
  24
  25 Source code comments
  26     Classes
  27         Each class should be shortly described in its header file.
  28
  29     Functions
  30         Public functions should be documented as well in the header file. Especially regarding side effects!
  31         (What does a programmer neeed to know in order to use this function without reading the whole source code?)
  32
  33     Inline comments
  34         are very helpful for commands (function calls, calculations) that are not obvious. For example, what
  35         does this function call do?
  36
  37             davinci.drawLine(0, y, scopeRect().size().width()-RGBParadeGenerator::distRight, y);
  38
  39         A short comment makes it obvious (also helps locating bugs when something needs to be fixed):
  40
  41             // Draw a horizontal line through the current mouse position
  42             davinci.drawLine(0, y, scopeRect().size().width()-RGBParadeGenerator::distRight, y);
  43
  44
  45 API documentation
  46     The docs can be generated by using doxygen (doxygen DoxyConfig in the main directory).
  47     See [1] for an overview of doxygen commands.
  48     Often used: \brief, \param, \return
  49
  50
  51 Coding style
  52     This part is based on Krita's HACKING file[2].
  53
  54     Indentation, Braces etc.
  55         4 Spaces for indentation. Always braces.
  56         This is, according to the Qt4 coding style, which is documented here:
  57         http://techbase.kde.org/Policies/Kdelibs_Coding_Style
  58
  59     Includes
  60         Avoid as much as possible #includes in header files; use forward declarations
  61         of classes.
  62
  63     Initializers
  64         Avoid as much as possible initializers in the body of the constructor. Use
  65         initializer lists instead.
  66
  67     Scope prefixes
  68         Use only m_ for class-level variables. No other scope prefixes; no g_, l_,
  69         no 'p' for pointer variables.
  70
  71     Shared pointers
  72         Use shared pointers wherever possible.
  73
  74     Getter/setter
  75         Getter/setters are named x() for getters and setX(int x) for setters. If you
  76         come across violations of this rule, change the code.
  77
  78     Function naming
  79         Functions should be named in camelBackedFashion, to conform to Qt's standards.
  80         If you encounter functions in c_style_like_this, feel free to rename. Also:
  81         verbNoun -- i.e., rotateLayer, not layer_rotate. The latter is a true c-ism,
  82         introduced by a language that needs to prefix the 'class' name to every function
  83         in order to have something that not quite OO.
  84
  85     Variable/Parameter names
  86         Variable/parameter names start with an undercast letter. A name composed of different
  87         words is done in camelBackedStyle.
  88
  89     Files and classes
  90         It's preferred (and strongly preferred) to have only one class per .h/.cpp file.
  91         (Which is logical, because otherwise you won't be able to keep to the naming scheme.)
  92
  93     Spaces
  94         Keep the source airy and open. In particular, there should be empty lines between function
  95         declarations and definitions.
  96
  97     Slots and signals
  98         Prefix slots with slot and signals with signal: slotUpdateSelection, signalSelectionUpdated.
  99
 100     Boolean operators
 101         Use the standard !, !=, ==, && etc style, not the "not", "and" etc. style. Keep kdenlive code
 102         using one, easily recognizable, C++ style.
 103
 104
 105     Exceptions
 106         These rules are merely guidelines for making the code consistent and more readable. In some cases
 107         it makes sense to not follow some of the points mentioned above.
 108
 109
 110 [1] http://www.stack.nl/~dimitri/doxygen/commands.html
 111 [2] http://quickgit.kde.org/?p=calligra.git&a=blob_plain&h=3e8fcab9dd3588c0228498af2795d3b714b73d42&f=krita/HACKING