Modify rule S6194 Improve rule description for coroutine cognitive co…

…mplexity CPP-4992

rules/S6194/rule.adoc

@@ -1,6 +1,25 @@
 == Why is this an issue?
 
-Cognitive Complexity is a measure of how hard the control flow of a function is to understand. Coroutines with high Cognitive Complexity will be difficult to maintain.
+"Cognitive complexity" is a measure of how hard the control flow of a function is to understand. Code with high cognitive complexity is hard to read, understand, test, and modify.
+
+This rule raises on coroutines with high cognitive complexity.
+
+As a rule of thumb, high cognitive complexity is a sign that the code should be refactored into smaller, easier-to-manage pieces.
+
+=== Which syntax in code does impact cognitive complexity score?
+
+Here are the core concepts:
+
+* **Cognitive complexity is incremented each time the code breaks the normal linear reading flow.** +
+This concerns, for example, loop structures, conditionals, catches, switches, jumps to labels, and conditions mixing multiple operators.
+* **Each nesting level increases complexity.** +
+During code reading, the deeper you go through nested layers, the harder it becomes to keep the context in mind.
+* **Method calls are free** +
+ A well-picked method name is a summary of multiple lines of code. 
+ A reader can first explore a high-level view of what the code is performing then go deeper and deeper by looking at called functions content. +
+__Note:__ This does not apply to recursive calls, those will increment cognitive score.
+
+The method of computation is fully detailed in the pdf linked in the resources.
 
 
 == Resources