devel:coding_style
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
devel:coding_style [2010-07-19 22:34] – old revision restored ach | devel: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 | + | DokuWiki is a very old project and coding styles vary within |
+ | |||
+ | **The official coding style to apply to all new code is [[https:// | ||
+ | |||
+ | When editing existing code you're encouraged | ||
===== Brackets and Indentations ===== | ===== Brackets and Indentations ===== | ||
- | You should indent your code by 4 **spaces** to mark logical blocks. Please **do not use tabs**. | + | You should indent your code by 4 **spaces** to mark logical blocks. Please **do not use tabs**. |
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.: | ||
<code php> | <code php> | ||
- | if ($foo == " | + | if ($foo == " |
call_bar(); | call_bar(); | ||
- | }elseif($foo == " | + | } elseif ($foo == " |
call_baz(); | call_baz(); | ||
- | }else{ | + | } else { |
call_other(); | call_other(); | ||
} | } | ||
Line 20: | Line 24: | ||
</ | </ | ||
- | ===== Lineendings ===== | + | Refer to PSR-12 for more details. |
- | Lines should end with a single linefeed character (UNIX style). Please try to avoid trailing whitespace. Have a look at my [[notes> | + | ===== 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 ===== | ===== Commenting ===== | ||
- | Each function and class should have a PHPDocumentor style comment, giving at least the function' | + | Each function and class should have a PHPDocumentor style comment, giving at least the function' |
+ | |||
+ | Author lines are optional, since we track authorship in git anyway. | ||
Example: | Example: | ||
Line 39: | Line 47: | ||
* @author | * @author | ||
* @param | * @param | ||
- | * @returns | + | * @return |
* | * | ||
*/ | */ | ||
- | function is_foo($in){ | + | function is_foo($in) |
- | ... | + | { |
+ | ... | ||
} | } | ||
</ | </ | ||
- | These comments are used for the [[http:// | + | These comments are used for the [[xref> |
- | ===== PHP closing tags ===== | + | ===== PHP Closing Tags ===== |
You should omit PHP's closing tags (''?>'' | You should omit PHP's closing tags (''?>'' | ||
- | **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() | + | > **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() |
+ | |||
+ | ===== Visibility and Type Hints ===== | ||
+ | |||
+ | Please do not use '' | ||
+ | |||
+ | 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 ===== | ===== Checking for Coding Style Violations ===== | ||
- | The development [[git]] checkout contains a coding standard setup for the use with [[http://pear.php.net/package/ | + | Code styles can be checked |
+ | |||
+ | === 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 ../ | ||
+ | |||
+ | # Check all files in a directory | ||
+ | cd _test | ||
+ | composer check ../ | ||
devel/coding_style.1279571651.txt.gz · Last modified: 2010-07-19 22:34 by ach