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