Important

You are browsing the documentation for version 4.1 of OroCommerce, OroCRM and OroPlatform, which is no longer maintained. Read version 5.1 (the latest LTS version) of the Oro documentation to get up-to-date information.

See our Release Process documentation for more information on the currently supported and upcoming releases.

Code Style

Code style is a set of conventions about how to write code. It is introduced for easier understanding of the large codebase by the wide-spread Oro community.

The following code styles are used in all Oro projects, except for projects based on the frameworks, libraries or CMS where other conventions have been adopted.

PHP Code Style

Standard

PSR-2 is considered a coding standard of the PHP code style.

Default line break separator

Default line break separator is LF (\n) - Unix and OS X style.

Note

To eliminate issues with this requirement, we recommend to configure IDE and always use appropriate line break separator.

DocBlock

Use PHPDoc approach to commenting your code.

Class DocBlock

It is required to add or update a DocBlock for every class you modify or produce. Include any information that helps clarify non-obvious behavior or conditions.

Method DocBlock

It is required to add or update a DocBlock for every method you modify or produce. Include the following information:

  • Any information that helps clarify non-obvious behavior or conditions.

    Note

    Description should briefly reflect the purpose and responsibility of a method. Avoid description that duplicates the method name.

  • The list of parameters, their types, and descriptions (@param), and, if the method returns any value, the type and description in the @return annotation.

    For example:

     1 /**
 2 * The method returns status of product inventory.
 3 *
 4 * Supported values are In Stock, Out of Stock, and Discontinued.
 5 *
 6 * @param string $SKU The product SKU (unique product id).
 7 *
 8 * @return string The inventory status of the product found by SKU.
 9 *
10 */

Property DocBlock

It is required to add or update a DocBlock for every property you produce or use in a new way. Include any information that helps clarify non-obvious behavior, conditions, or possible values.

Note

Description should briefly reflect the property purpose and data type. Avoid description that duplicates the property name.

DocBlock Sample

An example of correct DocBlock usage:

 1namespace Oro\Bundle\DataGridBundle\Datasource;
 2
 3use Doctrine\Common\Inflector\Inflector;
 4
 5use Symfony\Component\PropertyAccess\PropertyAccess;
 6
 7class ResultRecord implements ResultRecordInterface
 8{
 9   /**
10    * List of containers that are used in some specific way
11    *
12    * @var array
13    */
14   private $valueContainers = [];
15
16    /**
17     * @var array
18     */
19    private $entities = [];
20
21    /** @var string */
22    private $value = "";
23
24    /**
25     * @param array $containers
26     */
27    public function __construct($containers)
28    {
29        // ...
30    }
31
32    /**
33     * Get value of property by name
34     *
35     * @param  string $name
36     * @return string
37     */
38    public function getValue($name)
39    {
40        // ...
41        return $value
42    }
43
44    /**
45     * @return object|null
46     */
47    public function getRootEntity()
48    {
49        // ...
50        return $entity
51    }
52}

@deprecated usage

Elements that will be removed in a future version of the product must be marked as @deprecated.

Comment with deprecation details is optional.

The following is an example of @deprecated usage:

 1class ResultRecord
 2{
 3    /**
 4    * @deprecated deprecated since version 2.0
 5    */
 6    private $valueContainers = [];
 7
 8    //....
 9}
10
11
12/**
13 * @deprecated
14 */
15class ResultRecord
16{
17    //....
18{

@todo usage

@todo should be used for changes that are planned for the future (e.g., The method may be enhanced to handle more granular data validation).

Note

@todo provide clear description

Do not import classes from root namespace

Classes from the root namespace should not be imported.

Import internal PHP classes example:

1// incorrect
2use DateTime;
3$date = new DateTime();
4
5// correct
6$date = new \DateTime();

PHP code style continuous control

PHP code style is controlled by the PHP CodeSniffer tool installed on the continuous integration server according to the rules defined in the ruleset.xml file.

We highly recommended developers to configure appropriate code style inspections in the IDE or run these inspections manually before merging changes to the master branch. It prevents failures of the build that checks code standards.

Note

Information on how to enable PHP CodeSniffer inspection with the custom set of rules in the PHPStorm can be found in PHPStorm documentation.

PHP mess detector

To automatically control code, the quality detector is used, in addition to the code style detector tool. PHP Mess Detector (PHPMD) is a tool which can check PHP source code for potential problems. It can detect possible bugs, suboptimal code, unused parameters, and helps to follow SOLID principles. In addition to these, PHPMD contains several rules that check for code complexity and can tell if the code could be refactored to improve future maintenance efforts.

Cyclomatic complexity

Note

On the Oro projects, cyclomatic complexity MUST NOT exceed the limit of 15.

Cyclomatic complexity is determined by the number of decision points in a method plus one for the method entry. The decision points are ‘if’, ‘while’, ‘for’, and ‘case labels’ (see PHPMD). The testing strategy is to test each linearly independent path through the program. In this case, the number of test cases will equal the cyclomatic complexity of the program (see basis path testing).

There are many good reasons to limit cyclomatic complexity. Overly complex modules are more prone to error, harder to understand, test, and modify. Deliberately limiting complexity at all stages of software development, for example as a departmental standard, helps avoid the pitfalls associated with high complexity software. But there were occasional reasons for going beyond the agreed-upon limit. For instance, Thomas McCabe initially recommended exempting modules consisting of a single multi-way decision (“switch” or “case”) statements from the complexity limit. And suggested the most effective policy: “For each module, either limit cyclomatic complexity to 10 (as discussed earlier, an organization can substitute a similar number), or provide a written explanation of why the limit was exceeded.” (see Structured Testing: A Testing Methodology Using the Cyclomatic Complexity Metric).

Cyclomatic complexity limits suggestions are the following:

  • PHP: 1-4 is low complexity, 5-7 indicates moderate complexity, 8-10 is high complexity, and 11+ is very high complexity (see PHPMD).

  • Java 1–10 to be considered a Normal application, 11–20 Moderate application, 21–50 Risky application, more than 50 Unstable application (also see here, by GMetrics ).

  • .Net: 1 to 10 a simple program, without very much risk; 11 to 20 a more complex program, moderate risk; 21 to 50 a complex, high risk program; > 50 an un-testable program (very high risk).

  • Microsoft recommendation is to warn when Cyclomatic complexity is more than 25 (CA1502).

  • McCabe originally proposed the limit of 10 since it has significant supporting evidence, but limits as high as 15 have been used successfully as well.

NPath complexity

Important

The recommended limit of the NPath complexity is 200 (the default PHPMD limit).

The NPath metric computes the number of possible execution paths through a function, meaning how many “paths” there are in the flow of your code in the function. It is similar to the cyclomatic complexity, but it also takes into account the nesting of conditional statements and multi-part boolean expressions. So, you should avoid long functions with a lot of (nested) if/else statements.

@SuppressWarnings

It is allowed to use suppress warnings annotations in the following cases ONLY:

  1. @SuppressWarnings(PHPMD) in the code that was automatically generated by a third-party tool or library (example: EwsBundle/Ews).

  2. @SuppressWarnings(PHPMD.ExcessiveMethodLength) for the dataProvider in the PHPUnit tests in the install schema or data migrations.

  3. @SuppressWarnings(PHPMD.TooManyMethods) for the PHPUnit test case classes in the install schema or data migrations.

  4. @SuppressWarnings(PHPMD.CouplingBetweenObjects) in the install schema or data migrations.

  5. @SuppressWarnings(PHPMD.CyclomaticComplexity) for methods consisting of single multi-way decision (“switch” or “case”) statements, when the explanation on why the limit was exceeded is provided in the nearby comment.

  6. all @SuppressWarnings if there are plans to remove these warnings with appropriate @todo comment and ticket.

In all other cases, usage of the @SuppressWarnings MUST NOT be used.

php-cs-fixer usage

In order to reduce development time and automate part of the code preparation related to the code style fixes, it is suggested to use GitHub repository) - automated tool that fixes most code style issues in the code.

JavaScript Code Style

Standard

Google JavaScript Style Guide is considered as a code standard of the JavaScript code style.

JavaScript code style continuous control

JavaScript code style is controlled by the ESLint tool installed on the continuous integration server according to the rulests defined in the development repository in the root folder (example: .eslintrc.yml).

It is highly recommended to configure appropriate code style inspections in the IDE or run these inspections manually before committing the changes and merging it to the project repository.

Important

To enable the JavaScript code style checker in PHPStorm, navigate to “Languages & Frameworks > JavaScript > Code Quality Tools > ESLint” and select to use the configuration from .eslintrc.yml.

To run the check manually from the command line:

  1. First, you need to install the required js-modules in the application directory

    npm install

  2. Then, run ESLint to check JS files for code-style

    ./vendor/oro/platform/build/node_modules/.bin/eslint ./vendor/oro/ -c ./vendor/oro/platform/build/.eslintrc.yml –ignore-path ./vendor/oro/platform/build/.eslintignore

.NET Code Style

.NET code MUST follow the Microsoft Managed Recommended Rules. This code style is controlled on the continuous integration with StyleCop.

CSS and HTML Code Style

There are no defined code styles for the CSS and HTML.

It is recommended to use same code style that is used in Bootstrap.

See Also