Differences

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

--- devel:coding_style [2012-10-25 04:43] – Spelling: Lineendings -> Line Endings Matt2
+++ devel:coding_style [2023-11-13 21:13] (current) – [Checking for Coding Style Violations] andi
@@ Line 1: / Line 1: @@
 ====== Coding Style ======
-There are currently no really strict rules in how the code should be formatted but a few basic things should be attended to when adding code to DokuWiki.
+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**. Much code still uses 2 spaces; you should stick to this or change the whole file to 4 spaces.
+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.:
@@ Line 19: / Line 23: @@
 </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.
+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 and its author. Parameter and return value descriptions are encouraged but only mandatory if they are not obvious. If you enhance an existing function just add another author line.
+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:
@@ Line 42: / Line 50: @@
  *
  */
-function is_foo($in){
+function is_foo($in)
-...
+{
+    ...
 }
 </code>
-These comments are used for the [[http://dev.splitbrain.org/reference/dokuwiki/|autogenerated API Docs]].
+These comments are used for the [[xref>index|autogenerated API Docs]].
-===== PHP closing tags =====
+===== 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 =====
-The development [[git]] checkout contains a coding standard setup for the use with [[http://pear.php.net/package/PHP_CodeSniffer|PHP Code Sniffer]] in ''_cs/DokuWiki''.
+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