Updated Coding style policy (markdown)

2025-07-31 16:15:20 +02:00 · 2018-10-31 19:02:44 +01:00 · 2018-10-31 19:02:44 +01:00 · 33583b8698
commit 33583b8698
parent 89515eaa57
1 changed files with 303 additions and 1 deletions
--- a/Coding-style-policy.md
+++ b/Coding-style-policy.md
@ -6,6 +6,234 @@ This page explains the coding style policy for RSS-Bridge. Please make sure your

 _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.

+# Use tabs for indentation
+
+RSS-Bridge uses tabs for indentation on all PHP files in the repository.
+
+_Reference_: [`Generic.WhiteSpace.DisallowSpaceIndent`](https://github.com/squizlabs/PHP_CodeSniffer/blob/master/src/Standards/Generic/Sniffs/WhiteSpace/DisallowSpaceIndentSniff.php)
+
+# Maximum line length
+
+One line of code should have no more than **80 characters** (soft limit) and must never exceed **120 characters** (hard limit).
+
+_Notice_: Travis-CI enforces the hard limit of 120 characters. Maintainers may ask you to indent lines longer than 80 characters before merging. This is generally done to keep the code as readable and maintainable as possible.
+
+For long conditional statements, consider indenting the statement into multiple lines.
+
+<details><summary>Example</summary><div><br>
+
+**Bad** (the total length of the line is **94** characters)
+
+```PHP
+if($time !== false && (time() - $duration < $time) && (!defined('DEBUG') || DEBUG !== true)) {
+
+}
+```
+
+**Good** (add line breaks)
+
+```PHP
+if($time !== false
+&& (time() - $duration < $time)
+&& (!defined('DEBUG') || DEBUG !== true)) {
+
+}
+```
+
+</div></details><br>
+
+For long text, either add line feeds, or make use of the [`heredoc`](http://php.net/manual/en/language.types.string.php#language.types.string.syntax.heredoc) syntax.
+
+<details><summary>Example</summary><div><br>
+
+**Bad** (the total length of the line is **340** characters - from [Lorem Ipsum](https://www.lipsum.com/feed/html))
+
+```PHP
+$longtext = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse condimentum nec est eget posuere. Proin at sagittis risus. Fusce faucibus lectus leo, eu ornare velit tristique eu. Curabitur elementum facilisis ultricies. Praesent dictum fermentum lectus a rhoncus. Donec vitae justo metus. Sed molestie faucibus egestas.';
+```
+
+**Good** (use `heredoc` syntax - this will add line-breaks)
+
+```PHP
+$longtext = <<<EOD
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse
+condimentum nec est eget posuere. Proin at sagittis risus. Fusce faucibus
+lectus leo, eu ornare velit tristique eu. Curabitur elementum facilisis
+ultricies. Praesent dictum fermentum lectus a rhoncus. Donec vitae justo metus.
+Sed molestie faucibus egestas.
+EOD;
+```
+
+</div></details><br>
+
+_Reference_: [`Generic.Files.LineLength`](https://github.com/squizlabs/PHP_CodeSniffer/blob/master/src/Standards/Generic/Sniffs/Files/LineLengthSniff.php)
+
+# Calling functions
+
+Function calls must follow a few rules in order to maintain readability throughout the project:
+
+**Do not add whitespace before the opening parenthesis**
+
+<details><summary>Example</summary><div><br>
+
+**Bad**
+
+```PHP
+$result = my_function ($param);
+```
+
+**Good**
+
+```PHP
+$result = my_function($param);
+```
+
+</div></details><br>
+
+**Do not add whitespace after the opening parenthesis**
+
+<details><summary>Example</summary><div><br>
+
+**Bad**
+
+```PHP
+$result = my_function( $param);
+```
+
+**Good**
+
+```PHP
+$result = my_function($param);
+```
+
+</div></details><br>
+
+**Do not add a space before the closing parenthesis**
+
+<details><summary>Example</summary><div><br>
+
+**Bad**
+
+```PHP
+$result = my_function($param );
+```
+
+**Good**
+
+```PHP
+$result = my_function($param);
+```
+
+</div></details><br>
+
+**Do not add a space before a comma**
+
+<details><summary>Example</summary><div><br>
+
+**Bad**
+
+```PHP
+$result = my_function($param1 ,$param2);
+```
+
+**Good**
+
+```PHP
+$result = my_function($param1, $param2);
+```
+
+</div></details><br>
+
+**Add a space after a comma**
+
+<details><summary>Example</summary><div><br>
+
+**Bad**
+
+```PHP
+$result = my_function($param1,$param2);
+```
+
+**Good**
+
+```PHP
+$result = my_function($param1, $param2);
+```
+
+</div></details><br>
+
+_Reference_: [`Generic.Functions.FunctionCallArgumentSpacing`](https://github.com/squizlabs/PHP_CodeSniffer/blob/master/src/Standards/Generic/Sniffs/Functions/FunctionCallArgumentSpacingSniff.php)
+
+# Use UPPERCASE for constants
+
+As in most languages, constants should be written in UPPERCASE. This does not apply to keywords (see below)!
+
+<details><summary>Example</summary><div><br>
+
+**Bad**
+
+```PHP
+const pi = 3.14;
+```
+
+**Good**
+
+```PHP
+const PI = 3.14;
+```
+
+</div></details><br>
+
+_Reference_: [`Generic.NamingConventions.UpperCaseConstantName`](https://github.com/squizlabs/PHP_CodeSniffer/blob/master/src/Standards/Generic/Sniffs/NamingConventions/UpperCaseConstantNameSniff.php)
+
+# Use lowercase for `true`, `false` and `null`
+
+`true`, `false` and `null` must be written in lower case letters.
+
+<details><summary>Example</summary><div><br>
+
+**Bad**
+
+```PHP
+if($condition === TRUE && $error === FALSE) {
+    return NULL;
+}
+```
+
+**Good**
+
+```PHP
+if($condition === true && $error === false) {
+    return null;
+}
+```
+
+</div></details><br>
+
+_Reference_: [`Generic.PHP.LowerCaseConstant`](https://github.com/squizlabs/PHP_CodeSniffer/blob/master/src/Standards/Generic/Sniffs/PHP/LowerCaseConstantSniff.php)
+
+# Use a single string instead of concatenating
+
+Concatenation is useful for combining variables with other variables or static text. It should not be used to combine two sets of static text. See also: [Maximum line length](#maximum-line-length)
+
+<details><summary>Example</summary><div><br>
+
+**Bad**
+
+```PHP
+$text = 'This is' . 'a bad idea!';
+```
+
+**Good**
+
+```PHP
+$text = 'This is a good idea!';
+```
+
+</div></details><br>
+
+_Reference_: [`Generic.Strings.UnnecessaryStringConcat`](https://github.com/squizlabs/PHP_CodeSniffer/blob/master/src/Standards/Generic/Sniffs/Strings/UnnecessaryStringConcatSniff.php)
+
 # Do not write empty statements

 Empty statements are considered bad practice and must be avoided.
@ -34,6 +262,36 @@ if(!$condition) {

 _Reference_: [`Generic.CodeAnalysis.EmptyStatement`](https://github.com/squizlabs/PHP_CodeSniffer/blob/master/src/Standards/Generic/Sniffs/CodeAnalysis/EmptyStatementSniff.php)

+# Use 'elseif' instead of 'else if'
+
+For sake of consistency `else if` is considered bad practice.
+
+<details><summary>Example</summary><div><br>
+
+**Bad**
+
+```PHP
+if($conditionA) {
+
+} else if($conditionB) {
+
+}
+```
+
+**Good**
+
+```PHP
+if($conditionA) {
+
+} elseif($conditionB) {
+
+}
+```
+
+</div></details><br>
+
+_Reference_: [`PSR2.ControlStructures.ElseIfDeclaration`](https://github.com/squizlabs/PHP_CodeSniffer/blob/master/src/Standards/PSR2/Sniffs/ControlStructures/ElseIfDeclarationSniff.php)
+
 # Do not write unconditional if-statements

 If-statements without conditions are considered bad practice and must be avoided.
@ -106,4 +364,48 @@ class MyClass extends BaseClass {

 </div></details><br>

-_Reference_: [`Generic.CodeAnalysis.UselessOverridingMethod`](https://github.com/squizlabs/PHP_CodeSniffer/blob/master/src/Standards/Generic/Sniffs/CodeAnalysis/UselessOverridingMethodSniff.php)
+_Reference_: [`Generic.CodeAnalysis.UselessOverridingMethod`](https://github.com/squizlabs/PHP_CodeSniffer/blob/master/src/Standards/Generic/Sniffs/CodeAnalysis/UselessOverridingMethodSniff.php)
+
+# Parameters with default values must appear last in functions
+
+It is considered good practice to make parameters with default values last in function declarations.
+
+<details><summary>Example</summary><div><br>
+
+**Bad**
+
+```PHP
+function showTitle($duration = 60000, $title) { ... }
+```
+
+**Good**
+
+```PHP
+function showTitle($title, $duration = 60000) { ... }
+```
+
+</div></details><br>
+
+_Reference_: [`PEAR.Functions.ValidDefaultValue`](https://github.com/squizlabs/PHP_CodeSniffer/blob/master/src/Standards/PEAR/Sniffs/Functions/ValidDefaultValueSniff.php)
+
+# Use PascalCase for class names
+
+Class names must be written in [PascalCase](http://wiki.c2.com/?PascalCase).
+
+<details><summary>Example</summary><div><br>
+
+**Bad**
+
+```PHP
+class mySUPERclass { ... }
+```
+
+**Good**
+
+```PHP
+class MySuperClass { ... }
+```
+
+</div></details><br>
+
+_Reference_: [`PEAR.NamingConventions.ValidClassName`](https://github.com/squizlabs/PHP_CodeSniffer/blob/master/src/Standards/PEAR/Sniffs/NamingConventions/ValidClassNameSniff.php)