kwin/doc/coding-conventions.md

0001 # Coding Conventions
0002
0003 This document describes some of the recommended coding conventions that should be followed in KWin.
0004
0005 For KWin, it is recommended to follow the KDE Frameworks Coding Style.
0006
0007
0008 ## `auto` Keyword
0009
0010 Optionally, you can use the `auto` keyword in the following cases. If in doubt, for example if using
0011 `auto` could make the code less readable, do not use `auto`. Keep in mind that code is read much more
0012 often than written.
0013
0014 * When it avoids repetition of a type in the same statement.
0015
0016   ```
0017   auto something = new MyCustomType;
0018   auto keyEvent = static_cast<QKeyEvent *>(event);
0019   auto myList = QStringList({ "FooThing",  "BarThing" });
0020   ```
0021
0022 * When assigning iterator types.
0023
0024   ```
0025   auto it = myList.const_iterator();
0026   ```
0027
0028
0029 ## `QRect::right()` and `QRect::bottom()`
0030
0031 For historical reasons, the `QRect::right()` and `QRect::bottom()` functions deviate from the true
0032 bottom-right corner of the rectangle. Note that this is not the case for the `QRectF` class.
0033
0034 As a general rule, avoid using `QRect::right()` and `QRect::bottom()` as well methods that operate
0035 on them. There are exceptions, though.
0036
0037 Exception 1: you can use `QRect::moveRight()` and `QRect::moveBottom()` to snap a `QRect` to
0038 another `QRect` as long as the corresponding borders match, for example
0039
0040 ```
0041 // Ok
0042 rect.moveRight(anotherRect.right());
0043 rect.moveBottom(anotherRect.bottom());
0044 rect.moveBottomRight(anotherRect.bottomRight());
0045
0046 // Bad
0047 rect.moveRight(anotherRect.left() - 1); // must be rect.moveLeft(anotherRect.left() - rect.width());
0048 rect.moveBottom(anotherRect.top() - 1); // must be rect.moveTop(anotherRect.top() - rect.height());
0049 rect.moveBottomRight(anotherRect.topLeft() - QPoint(1, 1));
0050 ```
0051
0052 Exception 2: you can use `QRect::setRight()` and `QRect::setBottom()` to clip a `QRect` by another
0053 `QRect` as long as the corresponding borders match, for example
0054
0055 ```
0056 // Ok
0057 rect.setRight(anotherRect.right());
0058 rect.setBottom(anotherRect.bottom());
0059 rect.setBottomRight(anotherRect.bottomRight());
0060
0061 // Bad
0062 rect.setRight(anotherRect.left());
0063 rect.setBottom(anotherRect.top());
0064 rect.setBottomRight(anotherRect.topLeft());
0065 ```
0066
0067 Exception 3: you can use `QRect::right()` and `QRect::bottom()` in conditional statements as long
0068 as the compared borders are the same, for example
0069
0070 ```
0071 // Ok
0072 if (rect.right() > anotherRect.right()) {
0073     return;
0074 }
0075 if (rect.bottom() > anotherRect.bottom()) {
0076     return;
0077 }
0078
0079 // Bad
0080 if (rect.right() > anotherRect.left()) {
0081     return;
0082 }
0083 if (rect.bottom() > anotherRect.top()) {
0084     return;
0085 }
0086 ```