Differential D27060 Diff 74906 doc/coding-conventions.md

Changeset View

Standalone View

doc/coding-conventions.md

This file was added.

1		# Coding Conventions
2
3		This document describes some of the recommended coding conventions that should be followed in KWin.
4
5		For KWin, it is recommended to follow the KDE Frameworks Coding Style.
6
7
8		## `auto` Keyword
9
10		Optionally, you can use the `auto` keyword in the following cases. If in doubt, for example if using
11		`auto` could make the code less readable, do not use `auto`. Keep in mind that code is read much more
12		often than written.
13
14		* When it avoids repetition of a type in the same statement.
15
16		```
17		auto something = new MyCustomType;
18		auto keyEvent = static_cast<QKeyEvent *>(event);
19		auto myList = QStringList({ "FooThing", "BarThing" });
20		```
21
22		* When assigning iterator types.
23
24		```
25		auto it = myList.const_iterator();
26		```
27
28
29		## `QRect::right()` and `QRect::bottom()`
30
31		For historical reasons, the `QRect::right()` and `QRect::bottom()` functions deviate from the true
32		bottom-right corner of the rectangle. Note that this is not the case for the `QRectF` class.
33
34		As a general rule, avoid using `QRect::right()` and `QRect::bottom()` as well methods that operate
35		on them. There are exceptions, though.
36
37		Exception 1: you can use `QRect::moveRight()` and `QRect::moveBottom()` to snap a `QRect` to
38		another `QRect` as long as the corresponding borders match, for example
39
	davidedmundsonUnsubmitted Not Done please say another QRect instead of rectangle. QRectF source; QRect target; target.setRight(source.right()); is problematic davidedmundson: please say another QRect instead of rectangle. QRectF source; QRect target; target.setRight…
40		```
41		// Ok
42		rect.moveRight(anotherRect.right());
43		rect.moveBottom(anotherRect.bottom());
44		rect.moveBottomRight(anotherRect.bottomRight());
45
46		// Bad
47		rect.moveRight(anotherRect.left() - 1); // must be rect.moveLeft(anotherRect.left() - rect.width());
48		rect.moveBottom(anotherRect.top() - 1); // must be rect.moveTop(anotherRect.top() - rect.height());
49		rect.moveBottomRight(anotherRect.topLeft() - QPoint(1, 1));
50		```
51
52		Exception 2: you can use `QRect::setRight()` and `QRect::setBottom()` to clip a `QRect` by another
53		`QRect` as long as the corresponding borders match, for example
54
55		```
56		// Ok
57		rect.setRight(anotherRect.right());
58		rect.setBottom(anotherRect.bottom());
59		rect.setBottomRight(anotherRect.bottomRight());
60
61		// Bad
62		rect.setRight(anotherRect.left());
63		rect.setBottom(anotherRect.top());
64		rect.setBottomRight(anotherRect.topLeft());
65		```
66
67		Exception 3: you can use `QRect::right()` and `QRect::bottom()` in conditional statements as long
68		as the compared borders are the same, for example
69
70		```
71		// Ok
72		if (rect.right() > anotherRect.right()) {
73		return;
74		}
75		if (rect.bottom() > anotherRect.bottom()) {
76		return;
77		}
78
79		// Bad
80		if (rect.right() > anotherRect.left()) {
81		return;
82		}
83		if (rect.bottom() > anotherRect.top()) {
84		return;
85		}
86		```