Updated Coding style policy (markdown)

Coding-style-policy.md

@@ -1,62 +1,109 @@
-_**WORK IN PROGRESS: nothing described here should be considered as definitive or mandatory**_
+**WORK IN PROGRESS (by @LogMANOriginal)** Please refer to [phpcs.xml](https://github.com/RSS-Bridge/rss-bridge/blob/master/phpcs.xml) for a complete list of policies.
-## Indentation
 
-* Proposal 1
+***
+
+This page explains the coding style policy for RSS-Bridge. Please make sure your code is compliant before opening a pull request.
+
+_Notice_: RSS-Bridge uses [Travis-CI](https://travis-ci.org/) to check code quality. You will automatically be notified if issues were found in your pull request. You must fix those issues before it can be merged.
+
+# Do not write empty statements
+
+Empty statements are considered bad practice and must be avoided.
+
+<details><summary>Example</summary><div><br>
+
+**Bad**
+
+```PHP
+if($condition) {
+    // empty statement
+} else {
+    // do something here
+}
+```
+
+**Good** (invert condition)
+
+```PHP
+if(!$condition) {
+    // do something
+}
+```
+
+</div></details><br>
+
+_Reference_: [`Generic.CodeAnalysis.EmptyStatement`](https://github.com/squizlabs/PHP_CodeSniffer/blob/master/src/Standards/Generic/Sniffs/CodeAnalysis/EmptyStatementSniff.php)
+
+# Do not write unconditional if-statements
+
+If-statements without conditions are considered bad practice and must be avoided.
+
+<details><summary>Example</summary><div><br>
+
+```PHP
+if(true) {
+
+}
+```
+
+</div></details><br>
+
+_Reference_: [`Generic.CodeAnalysis.UnconditionalIfStatement`](https://github.com/squizlabs/PHP_CodeSniffer/blob/master/src/Standards/Generic/Sniffs/CodeAnalysis/UnconditionalIfStatementSniff.php)
+
+# Do not use final statements inside final classes
+
+Final classes cannot be extended, so it doesn't make sense to add the final keyword to class members.
+
+<details><summary>Example</summary><div><br>
+
+**Bad**
+
+```PHP
+final class MyClass {
+    final public function MyFunction() {
 
-    Use two space characters for each indentation level
-    ```PHP
-    if ( true ){
-      echo true;
-    } else{
-      echo false;
     }
-    ```
+}
+```
 
-* Proposal 2
+**Good** (remove the final keyword from class members)
 
-	Use one tab per indentation level (rendered as 4 spaces in GitHub)
+```PHP
-	```PHP
+final class MyClass {
-	if(true){
+    public function MyFunction() {
-		echo true;
-	} else{
-		echo false;
-	}
-	```
 
-## Trailing white spaces
+    }
+}
+```
 
-* Proposal 1
+</div></details><br>
 
-    Lines must be trimmed of any trailing white spaces
+_Reference_: [`Generic.CodeAnalysis.UnnecessaryFinalModifier`](https://github.com/squizlabs/PHP_CodeSniffer/blob/master/src/Standards/Generic/Sniffs/CodeAnalysis/UnnecessaryFinalModifierSniff.php)
 
-## Line length
+# Do not override methods to call their parent
 
-* Proposal 1
+It doesn't make sense to override a method only to call their parent. When overriding methods, make sure to add some functionality to it.
 
-    Lines must be limited to 80 characters
+<details><summary>Example</summary><div><br>
 
-* Proposal 2
+**Bad**
 
-	Lines should have a length of less than 80 characters where possible. The maximum length for one line is 120 characters.
+```PHP
+class MyClass extends BaseClass {
+    public function BaseFunction() {
+        parent::BaseFunction();
+    }
+}
+```
 
-## Variables, functions, methods and class naming
+**Good** (don't override the function)
 
-* Proposal 1
+```PHP
+class MyClass extends BaseClass {
 
-	```PHP
+}
-	var $thisVariable;
+```
-	function thisFunction(){}
-	class thisClass { 
-		function thisMethod(){}
- 	}
-	```
 
-* Proposal 2
+</div></details><br>
 
-	```PHP
+_Reference_: [`Generic.CodeAnalysis.UselessOverridingMethod`](https://github.com/squizlabs/PHP_CodeSniffer/blob/master/src/Standards/Generic/Sniffs/CodeAnalysis/UselessOverridingMethodSniff.php)
-	var $thisVariable; // camelCase
-	function this_function(){} // lower-case & underscore ('_')
-	class ThisClass { // UpperCamelCase (PascalCase)
-		function ThisMethod(){} // UpperCamelCase (PascalCase)
-	}
-	```