DokuWiki

It's better when it's simple

User Tools

Site Tools

Trace:
devel:coding_style

Differences

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

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
devel:coding_style [2019-01-07 20:30] – [Checking for Coding Style Violations] Add 3.x standards path phy25devel:coding_style [2023-11-13 21:13] (current) – [Checking for Coding Style Violations] andi
Line 1: Line 1:
 ====== Coding Style ====== ====== 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.
  
-It should be noted that for the DokuWiki core applying of the PSR2 coding style is work in progress (branch ''psr2''). The rules of this coding style can be viewed at https://www.php-fig.org/psr/psr-2/. 
 ===== Brackets and Indentations ===== ===== 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.: 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 20: Line 23:
  
 </code> </code>
 +
 +Refer to PSR-12 for more details.
  
 ===== Line Endings ===== ===== 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 ===== ===== 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: Example:
Line 43: Line 50:
  *  *
  */  */
-function is_foo($in) {+function is_foo($in) 
 +{
     ...     ...
 } }
Line 49: Line 57:
  
 These comments are used for the [[xref>index|autogenerated API Docs]]. These comments are used for the [[xref>index|autogenerated API Docs]].
 +
 ===== PHP Closing Tags ===== ===== PHP Closing Tags =====
  
Line 55: Line 64:
 > **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. > **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 ===== +===== Visibility and Type Hints =====
- +
-Even though some core code still uses PHP4 compatible ''var'' declarations you're encouraged to use proper PHP5 visibility declarations.+
  
 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. 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.
  
-===== Checking for Coding Style Violations =====+When using type hints be aware of the minimal supported PHP version for DokuWiki and don't use features not available in it.
  
-The development [[Git]] checkout contains a coding standard setup for the use with [[http://pear.php.net/package/PHP_CodeSniffer|PHP_CodeSniffer]] in ''_cs/DokuWiki''.+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.
  
-=== Setup ===+===== Checking for Coding Style Violations =====
  
-To install PHP_CodeSniffer run the following in your shell.+Code styles can be checked with [[https://github.com/squizlabs/PHP_CodeSniffer|PHP_CodeSniffer]]. A configuration file is located in the ''_test'' directory.
  
-    pear install PHP_CodeSniffer +=== Setup ===
- +
-Link the DokuWiki coding standard to the CodeSniffer directory.  You may need to adjust the paths depending upon your operating system. +
- +
-    # PHP_CodeSniffer Version 2.x +
-    ln -s /path/to/dokuwiki/_cs/DokuWiki /usr/share/pear/PHP/CodeSniffer/Standards/DokuWiki +
-     +
-    # PHP_CodeSniffer Version 3.x +
-    ln -s /path/to/dokuwiki/_cs/DokuWiki /usr/share/pear/PHP/CodeSniffer/src/Standards/DokuWiki+
  
-Set DokuWiki to be the default standard.+Install via [[composer]]:
  
-    phpcs --config-set default_standard DokuWiki+    cd _test 
 +    composer install
  
-Note that the provided DokuWiki coding standard is for PHP_CodeSniffer 2.x. PHP_CodeSniffer 3.x has breaking changes which result in errors indicating that the interface ''PHP_CodeSniffer_Sniff'' was not found. 
  
 === Usage === === Usage ===
Line 90: Line 89:
  
     # Check a single file     # Check a single file
-    phpcs myfile.php+    cd _test 
 +    composer check ../path/to/myfile.php
          
     # Check all files in a directory     # Check all files in a directory
-    phpcs /path/to/directory+    cd _test 
 +    composer check ../path/to/directory
  
devel/coding_style.1546889432.txt.gz · Last modified: 2019-01-07 20:30 by phy25
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki

Global DokuWiki Links