Front.id

Introduction

We expect our code to have certain level of quality and there're automatic tools to help us achieve it, and as a minimum we need to follow common Coding Standards. In this case we need to review common standards + Drupal Coding Standards.

Why we review Coding Standards?

Following a consistent coding standard helps to improve the quality of software systems. The key to a good standard coding is consistency. This consistency needs to be found within the standard itself (in other words, you need to make sure that guidelines don’t contradict one another) but also within the source code that uses the standard. A completed source code should reflect a harmonized style, as if a single developer had written all the code in one session.

These are certain factors that you have to bear in mind while formulating a code:

• You need to ensure that the code is readable by others and it's properly spaced out. For this:
  • You need to define different sections by dividing blocks of code into paragraphs.
  • You need to use the same indentation to depict where the control structures start and end and clearly indicate where the code within them it's located.
• Your variable naming conventions should be consistent throughout the code (i.e. camelCase, snake_case,...). They should describe the data they contain.
• You have to name the functions according to what they perform.
• Your coding should be such that when you return to it later you should be able to understand it without reading every line.
• You need to follow the appropriate method to comment the work.
• Avoid using complex language functions or constructs that are difficult to comprehend.

Implementing coding standards in your software has numerous advantages.

Composer, PHP Code Sniffer and Drupal Coding Standards

Install Coder with composer:

$ composer global require drupal/coder

Custom setup using for Drupal Coding Standards.

Add symbolic path to support Drupal and DrupalPractice Standard:

$ ln -s ~/.composer/vendor/drupal/coder/coder_sniffer/Drupal ~/.composer/vendor/squizlabs/php_codesniffer/src/Standards/Drupal
$ ln -s ~/.composer/vendor/drupal/coder/coder_sniffer/DrupalPractice ~/.composer/vendor/squizlabs/php_codesniffer/src/Standards/DrupalPractice

If you're using bash, edit $HOME/.bashrc (or $HOME/.bash_profile).

alias drupalcs="~/.composer/vendor/bin/phpcs --colors --standard=~/.composer/vendor/drupal/coder/coder_sniffer/Drupal --extensions=php,module,inc,install,test,profile,theme,js,css,info,txt,md"

If you added symbolic links:

alias drupalcs="~/.composer/vendor/bin/phpcs --colors --standard=Drupal --extensions=php,module,inc,install,test,profile,theme,js,css,info,txt,md"

source .bashrc

Execution example:

$ drupalcs modules/contrib/codesnippet/

FILE: .../web/modules/contrib/codesnippet/codesnippet.module
----------------------------------------------------------------------
FOUND 4 ERRORS AND 3 WARNINGS AFFECTING 4 LINES
----------------------------------------------------------------------
 15 | WARNING | Hook implementations should not duplicate @param
    |         | documentation
 15 | ERROR   | Missing parameter comment
 16 | WARNING | Hook implementations should not duplicate @param
    |         | documentation
 16 | ERROR   | Missing parameter comment
 35 | WARNING | Hook implementations should not duplicate @param
    |         | documentation
 35 | ERROR   | Missing parameter comment
 37 | ERROR   | Type hint "array" missing for $variables
----------------------------------------------------------------------

Time: 113ms; Memory: 8Mb

Drupal vs DrupalPractice

Coder contains "sniffs" for PHP CodeSniffer. These "sniffs" tell PHP CodeSniffer whether code meets Drupal coding standards or not. Specifically there are two rulesets, Drupal and DrupalPractice. The first one is intended to enforce the general standards and the second – previously known as DrupalPractice sniffer – is aimed at module developers who want to avoid common mistakes.

PHP Code Beautifier and Fixer

PHP Code Beautifier and Fixer fixes violations of a defined coding standard.

PHP Code Beautifier and Fixer is part of a set of two PHP scripts; the main phpcs script that tokenizes PHP, JavaScript and CSS files to detect violations of a defined coding standard, and a second phpcbf script to automatically correct coding standard violations. PHP_CodeSniffer is an essential development tool that ensures your code remains clean and consistent.

If you're using bash, edit $HOME/.bashrc (or $HOME/.bash_profile).

alias drupalcbf="phpcbf --standard=Drupal --extensions='php,module,inc,install,test,profile,theme,css,info,txt,md'"

Execution example:

$ drupalcbf modules/contrib/codesnippet                                                                                                        
Changing into directory /modules/contrib/codesnippet/src/Plugin/CKEditorPlugin                                                                                      
Processing CodeSnippet.php [PHP => 950 tokens in 126 lines]... DONE in 37ms (0 fixable violations)                                                                                                        
Changing into directory /modules/contrib/codesnippet                                                                                                                
Processing README.txt [PHP => 114 tokens in 114 lines]... DONE in 3ms (0 fixable violations)                                                                                                              
Processing codesnippet.libraries.yml [PHP => 284 tokens in 284 lines]... DONE in 5ms (1 fixable violations)                                                                                               
        => Fixing file: 0/1 violations remaining [made 2 passes]... DONE in 29ms                                                                                                                          
Processing codesnippet.install [PHP => 224 tokens in 35 lines]... DONE in 7ms (0 fixable violations)                                                                                                      
Changing into directory /modules/contrib/codesnippet/config/install                                                                                                 
Processing codesnippet.settings.yml [PHP => 33 tokens in 33 lines]... DONE in 1ms (1 fixable violations)                                                                                                  
        => Fixing file: 0/1 violations remaining [made 2 passes]... DONE in 10ms                                                                                                                          
Changing into directory /modules/contrib/codesnippet
Processing codesnippet.info.yml [PHP => 13 tokens in 13 lines]... DONE in 4ms (0 fixable violations)
Processing LICENSE.txt [PHP => 339 tokens in 339 lines]... DONE in 8ms (0 fixable violations)
Processing codesnippet.module [PHP => 376 tokens in 55 lines]... DONE in 13ms (0 fixable violations)
Patched 2 files
Time: 165ms; Memory: 8Mb

Drupal Coding Standards integration with PhpStorm

Drupal Coding Standards Fixer integration with PhpStorm

PHP-CS-Fixer setup

Open PHPStorm, Preferences > Tools > External Tools and enter these values:

• Program, edit to match your path where PHP-CS-Fixer lives:
  • ~/.composer/vendor/bin/phpcbf
• Parameters:
  • --standard=Drupal --extensions='php,module,inc,install,test,profile,theme,css,info,txt,md' $FileDir$/$FileName$
• Working directory:
  • $ProjectFileDir$

PHP-CS-Fixer keymap

Now we set up a shortcut.

• Go to Preferences > Keymap and search for "PHP Fixer" (or whatever name you gave it). Add whatever shortcut you like, I'm using:
  • Shift + Alt + K

Running

References:

• Coder
• Installing Coder Sniffer
• Command Line Usage
• PHP Code Sniffer PhpStorm
• Drupal Support PhpStorm
• PHP Code Beautifier and Fixer