Differences

This shows you the differences between two versions of the page.

--- devel:coding_style [2015-05-18 14:44] – created 218.50.181.98
+++ devel:coding_style [2023-11-13 21:13] (current) – [Checking for Coding Style Violations] andi
@@ Line 1: / Line 1: @@
-hib;
+====== Coding Style ======
+DokuWiki is a very old project and coding styles vary within the code.
+**The official coding style to apply to all new code is [[https://www.php-fig.org/psr/psr-12/|PSR-12]]**.
+When editing existing code you're encouraged to update the coding style. When you do, it is recommended to do code reformatting in a commit separate from your code changes.
+===== Brackets and Indentations =====
+You should indent your code by 4 **spaces** to mark logical blocks. Please **do not use tabs**. Some ancient code may still use 2 spaces; you should stick to this or change the whole file to 4 spaces.
+Opening brackets should start on the same line as the keyword, closing bracket should be aligned below the first letter of the starting keyword. E.g.:
+<code php>
+if ($foo == "bar") {
+    call_bar();
+} elseif ($foo == "baz") {
+    call_baz();
+} else {
+    call_other();
+}
+</code>
+Refer to PSR-12 for more details.
+===== Line Endings =====
+Lines should end with a single linefeed character (UNIX style). Please try to avoid trailing whitespace. Have a look at our page about [[Vim]] to see how to set up Vim to spot these easily. [[IntelliJ Idea]] will also help with keeping a consistent style.
+===== Commenting =====
+Each function and class should have a PHPDocumentor style comment, giving at least the function's purpose. Parameter and return value descriptions are encouraged but only mandatory if they are not obvious.
+Author lines are optional, since we track authorship in git anyway.
+Example:
+<code php>
+/**
+ * Check for foo in bar
+ *
+ * Checks if there is a foo in bar
+ *
+ * @author   Joe Schmoe <joe@example.com>
+ * @param    string $in your input
+ * @return   bool       true if foo in bar
+ *
+ */
+function is_foo($in)
+{
+    ...
+}
+</code>
+These comments are used for the [[xref>index|autogenerated API Docs]].
+===== PHP Closing Tags =====
+You should omit PHP's closing tags (''?>'') in all files to avoid premature output. This may sound strange but is actually mentioned in the [[http://www.php.net/manual/en/language.basic-syntax.instruction-separation.php|PHP manual]]:
+> **Note:** The closing tag of a PHP block at the end of a file is optional, and in some cases omitting it is helpful when using include()  or require(), so unwanted whitespace will not occur at the end of files, and you will still be able to add headers to the response later. It is also handy if you use output buffering, and would not like to see added unwanted whitespace at the end of the parts generated by the included files.
+===== Visibility and Type Hints =====
+Please do not use ''private'' but use ''protected'' instead. You never know when a subclass may want to overwrite functionality. Eg. some plugin might want to provide new functionality based on your plugin.
+When using type hints be aware of the minimal supported PHP version for DokuWiki and don't use features not available in it.
+In general be wary of overusing type hinting, especially in all public facing APIs. Changing it changes method signatures which has effects on all inheriting classes. A simple type hint change may break swathes of plugins with signature violations. As a rule of thumb, try sticking to object type hints and otherwise rely mostly on doc strings and PHP's duck typing.
+===== Checking for Coding Style Violations =====
+Code styles can be checked with [[https://github.com/squizlabs/PHP_CodeSniffer|PHP_CodeSniffer]]. A configuration file is located in the ''_test'' directory.
+=== Setup ===
+Install via [[composer]]:
+    cd _test
+    composer install
+=== Usage ===
+You can use PHP_CodeSniffer to check a single file or an entire directory including subdirectories using the following commands.
+    # Check a single file
+    cd _test
+    composer check ../path/to/myfile.php
+    # Check all files in a directory
+    cd _test
+    composer check ../path/to/directory