From d02e0a68701ae279e4c9ce47f465fa9f541c1e4a Mon Sep 17 00:00:00 2001
From: fourtf <tf.four@gmail.com>
Date: Sun, 13 Oct 2019 13:12:24 +0200
Subject: [PATCH] Added "comments" section to CONTRIBUTING.md

---
 CONTRIBUTING.md | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b57d417e..4ff789d9 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -9,6 +9,41 @@ Formatting
 
 Code is automatically formatted using `clang-format`. It take the burdon off of the programmer and ensures that all contributers use the same style (even if mess something up accidentally). We recommend that you set up automatic formatting on file save in your editor.
 
+# Comments
+
+Comments should only be used to:
+
+- Increase readablility (e.g. grouping member variables).
+- Containing information that can't be expressed in code.
+
+Try to structure your code so that comments are not required.
+
+#### Good example
+
+``` cpp
+/// Result is 0 if a == b, negative if a < b and positive if b > a.
+/// ^^^ You can't know this from the function signature!
+//      Even better: Return a "strong ordering" type.
+//          (but we don't have such a type right now)
+int compare(const QString &a, const QString &b);
+```
+
+#### Bad example
+
+``` cpp
+/*
+ * Matches a link and returns boost::none if it failed and a
+ * QRegularExpressionMatch on success. 
+ * ^^^ This comment just repeats the function signature!!!
+ * 
+ * @param text The text that will be checked if it contains a
+ * link
+ * ^^^ No need to repeat the obvious.
+ */
+boost::optional<QRegularExpressionMatch> matchLink(const QString &text);
+```
+
+
 # Code
 
 Arithmetic Types