From 5e9cf476273728c82e5ce6a97be04891d4a6d854 Mon Sep 17 00:00:00 2001
From: Ben Wiederhake <BenWiederhake.GitHub@gmx.de>
Date: Thu, 4 Nov 2021 23:07:12 +0100
Subject: [PATCH] Documentation: Recommend a comment style

---
 Documentation/CodingStyle.md | 40 ++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/Documentation/CodingStyle.md b/Documentation/CodingStyle.md
index 46c614aa0b5..2cd7aa1b941 100644
--- a/Documentation/CodingStyle.md
+++ b/Documentation/CodingStyle.md
@@ -512,6 +512,46 @@ draw_jpg(); // FIXME(joe): Make this code handle jpg in addition to the png supp
 draw_jpg(); // TODO: Make this code handle jpg in addition to the png support.
 ```
 
+Explain *why* the code does something. The code itself should already say what is happening.
+
+###### Wrong:
+
+```cpp
+i++; // Increment i.
+```
+
+```cpp
+// If the user clicks, toggle the timer state.
+catdog_widget.on_click = [&] {
+    if (advice_timer->is_active())
+        advice_timer->stop();
+    else
+        advice_timer->start();
+};
+```
+
+###### Right:
+
+```cpp
+i++; // Go to the next page.
+```
+
+```cpp
+// Let users toggle the advice functionality by clicking on catdog.
+catdog_widget.on_click = [&] {
+    if (advice_timer->is_active())
+        advice_timer->stop();
+    else
+        advice_timer->start();
+};
+```
+
+###### Even better:
+
+```cpp
+page_index++;
+```
+
 ### Overriding Virtual Methods
 
 The declaration of a virtual method inside a class must be declared with the `virtual` keyword. All subclasses of that class must either specify the `override` keyword when overriding the virtual method or the `final` keyword when overriding the virtual method and requiring that no further subclasses can override it.