Warning, /graphics/krita/HACKING is written in an unsupported language. File is not indexed.
0001 Since 1999, people have been hacking on Krita. Everyone brought their 0002 own coding style, their own code conventions, their own likes and 0003 dislikes. Me, (Boudewijn that is), I like indents of four spaces, and 0004 no scope prefixes for variables. However, in the interests of 0005 consistency, these are the rules new code should adhere to: 0006 0007 See also https://community.kde.org/Policies/Frameworks_Coding_Style -- 0008 that document is leading. 0009 0010 Qt vs STD vs Boost: 0011 0012 In general, use the Qt classes wherever possible, even if someone tells you 0013 that the STD class is better or whatever. We're dealing with a big project 0014 with lots of developers here and we should keep the code as consistent and 0015 easy to grasp as possible. Since people need to know Qt in the first place, 0016 keep to Qt. Discuss deviations on #krita 0017 0018 C++11 and C++14 0019 0020 Yes, but. 0021 0022 * Prefer normal functions over lambdas, unless really needed (e.g. when replacing 0023 the use of QSignalMapper) 0024 0025 * Try to avoid auto as a shortcut for the type name, except when used 0026 in range-based for-loops and iterators. Using auto as a replacement 0027 for a templated code (or inside templated code) is perfectly fine. 0028 0029 * Generic lambdas. Use generic lambdas only when you want to solve a 0030 problem that would otherwise require templates, not just as a shortcut for 0031 the argument typenames. 0032 0033 * auto as a deduced return type of functions that would otherwise require 0034 templates is perfectly fine 0035 0036 * In some cases it might be okay to use auto as a shortcut for the typename, 0037 e.g. when using very long types returned by boost. But better discuss that 0038 on #krita. 0039 0040 * Avoid the new sig/slot connection syntax _unless_ you are porting all of 0041 Krita to the new syntax. Sure, it has some advantages, but having two different 0042 ways of doing the same thing is begging for trouble and comprehension problems. 0043 0044 * For now, keep using Q_FOREACH, we're using it all over the place, and it has 0045 different constness semantics over the standard range-based for-loop. 0046 0047 * Use nullptr in new code. When changing existing code, make sure that 1) the whole 0048 .cpp/.h files pair uses the same style, 2) the change of the style outweigh the 0049 loss of the git-blame history (that is, your changes do already change the file 0050 significantly) 0051 0052 * Before using other new features, discuss on #krita so we can expand this list. 0053 0054 * Our minimum gcc version is 5.5.0, shipped with Ubuntu 16.04 0055 0056 0057 Indentation 0058 0059 With four spaces. Use the default kdelibs indentation 0060 (http://techbase.kde.org/Policies/Kdelibs_Coding_Style) 0061 0062 Includes 0063 0064 Avoid as much as possible #includes in header files; use forward declarations 0065 of classes. 0066 0067 Initializers 0068 0069 Avoid as much as possible initializers in the body of the constructor. Use 0070 initializer lists instead. Write the initializers as follows 0071 0072 Class(A a, B b) 0073 : Subclass(a) 0074 , m_b(b) 0075 { 0076 } 0077 0078 Note the location of the colon and comma. 0079 0080 It is also preferred to use {}-initialization for class members and 0081 glabal namespace scope variables, e.g. 0082 0083 class Foo 0084 { 0085 int m_value {0}; 0086 }; 0087 0088 namespace Bar 0089 { 0090 int SomeGlobalValue {0}; 0091 }; 0092 0093 Since Krita has a long history of usage =-initizalization everywhere, it is **not** 0094 recommended to use {}-initialization in function bodies, especially, when it results 0095 in a mix of styles in the same file. You can still use that as an exception to solve 0096 some specific problems like the most vexing parse. 0097 0098 Scope prefixes 0099 0100 Use only m_ for class-level variables. No other scope prefixes; no g_, l_, 0101 no 'p' for pointer variables. 0102 0103 Shared pointers 0104 0105 Use shared pointers wherever possible. Prefer Qt's shared pointer classes 0106 to our home-grown shared pointer classes. 0107 0108 Getter/setter 0109 0110 Krita doesn't use Qt's properties -- yet. If you want to introduce use of 0111 properties, convert any and all classes in Krita before committing. 0112 0113 Getter/setters are named 'x() for getters and setX(int x) for setters. If you 0114 come across violations of this rule, change the code. 0115 0116 Class naming 0117 0118 If you use a well-known design pattern, name the class according to the design 0119 pattern. All files should start with 'Kis', all classes with the 'Kis' prefix. 0120 This filename should be the same as the classname: KisNewClass.h, KisNewClass. 0121 0122 Filenames in plugins do not start with Kis; only in libraries. Do not make new 0123 classes that start with Ko. 0124 0125 Function naming 0126 0127 Functions should be named in camelBackedFashion, to conform to Qt's standards. 0128 If you encounter functions in c_style_like_this, feel free to rename. Also: 0129 verbNoun -- i.e., rotateLayer, not layer_rotate. The latter is a true c-ism, 0130 introduced by a language that needs to prefix the 'class' name to every function 0131 in order to have something that's not quite OO. 0132 0133 Variable/Parameter names 0134 0135 Variable/parameter names start with a lower case letter. A name composed of different 0136 words is done in camelBackedStyle. 0137 0138 Designer 0139 0140 Krita has started to use designer. All dialogs and all widgets that have a layout 0141 manager must be done in designer. Do not add code or signal/slot connections 0142 in designer. 0143 0144 Enums 0145 0146 All enums should be prefixed with 'enum'. 0147 0148 Namespaces 0149 0150 Currently, we only use anonymous namespaces for things like undo 0151 commands. For the rest, some classes have a 'Kis' prefix, others don't. This should 0152 be made consistent, and we might want to use namespaces to keep all of Krita 0153 inside. 0154 0155 Files and classes 0156 0157 It's preferred (and strongly preferred) to have only one class per .h/.cpp file. 0158 (Which is logical, because otherwise you won't be able to keep to the naming scheme.) 0159 0160 Spaces 0161 0162 Keep the source airy and open. In particular, there should be empty lines between function 0163 declarations and definitions. 0164 0165 Slots and signals 0166 0167 Prefix slots with slot and signals with sig: slotUpdateSelection, sigSelectionUpdated. 0168 0169 Boolean operators 0170 0171 Use the standard !, !=, ==, && etc style, not the "not", "and" etc. style. Keep krita code 0172 using one, easily recognizable, C++ style. 0173 0174 0175 With Krita now supporting Python scripting, we need guidelines for these as well. 0176 These guidelines are preliminary and may be further refined in the future. 0177 0178 To keep it simple, we have chosen to follow the style guide suggested by Python: PEP8. 0179 0180 All rules should be followed, except the max limit of 79 characters per line. As this 0181 can reduce readability in some cases, this rule is optional. 0182 0183 The full PEP8 specification is available here: https://www.python.org/dev/peps/pep-0008/ 0184 0185 To check compliance you can run pep8.py against the code. 0186 You can also use autopep8.py to automatically fix detected compliance issues. 0187 0188 pep8.py can be downloaded via Python's package manager (pip) [https://pypi.python.org/pypi/pep8], 0189 or your distribution's package manager. 0190 autopep8.py can also be downloaded via Python's package manager [https://pypi.python.org/pypi/autopep8], 0191 or your distribution's package manager. 0192 0193 Both of these scripts come bundled with the PyDev plugin, which is available for Eclipse and other IDEs. 0194 The PyDev integration can be configured to visually highlight portions of the code which is not in compliance, 0195 as well as run autopep8 via shortcuts. 0196 0197 pep8.py and autopep8.py can suppress select rules via the "--ignore" command line argument. 0198 To ignore the 79 characters per line rule, pep8.py can be called like this: 0199 0200 pep8.py --ignore=E501 0201 0202 You can read more about the error codes and what they mean here: 0203 http://pep8.readthedocs.io/en/release-1.7.x/intro.html#error-codes