Coding Standards in PrestaShop: Guidelines and Best Practices for Clear and Maintainable Code

PrestaShop is a collaborative, open-source project that continuously evolves with contributions from numerous developers worldwide. Due to the extensive number of contributors, it is essential to maintain uniform coding standards to ensure clarity, maintainability, and seamless integration of code. However, not all developers consistently follow these standards, which can complicate code integration and maintenance. This article outlines the coding standards recommended by PrestaShop, explaining why they matter and how to follow them effectively.

Why Coding Standards Matter

Having a unified coding style across a project simplifies collaboration, enhances readability, and makes bug detection and fixing easier. When code appears consistent regardless of its author, other developers can quickly grasp its structure and purpose. Unified standards help:

• Reduce the likelihood of errors.
• Simplify debugging.
• Improve readability and accessibility for new contributors.
• Facilitate future customizations and adaptations.

Moreover, consistent coding practices allow developers to more efficiently locate and fix issues, as they quickly understand the code's logic.

Key PrestaShop Standards

PrestaShop’s team adheres to specific coding standards to support readability, reliability, and code uniformity. Below are key guidelines to help you create quality code that aligns with PrestaShop requirements.

1. General Principles

All code files should follow these basic guidelines:

• File Encoding: Use UTF-8 encoding without BOM to prevent character display issues and ensure compatibility across environments.
• Line Endings: Use Unix LF (\n) line endings, as this is the standard for most open-source projects.
• Trailing Blank Line: Add a blank line at the end of each file. This helps prevent issues with version control tools like Git and makes reviewing code changes easier.

2. Code Documentation

Proper documentation helps other developers understand the purpose and use of your code. Here are a few key points:

• Class and Method Descriptions: Each class and method should contain a doc block that describes its purpose and primary parameters. If you find it difficult to describe the purpose of a class, it may be too complex and could benefit from being split into multiple classes.
• Parameter and Return Types: Use annotations to specify parameter and return types. For instance, indicate the data type (string, array, object) and clarify how it’s used to provide context and reduce misunderstandings.

Documentation example:

3. PHP Code: Adhering to PSR-2 and Symfony Standards

PrestaShop uses PSR-2 standards to maintain PHP code readability and uniformity, as well as Symfony standards. Key points include:

• Indentation and Formatting: All files should use spaces for indentation (4 spaces per level).
• Yoda Conditions: Use if ('value' == $variable) instead of if ($variable == 'value') to prevent accidental assignments instead of comparisons. While not required, Yoda conditions are recommended to avoid certain types of errors.
• PHP CS Fixer: This tool automatically checks and fixes code to align with PSR-2 and Symfony standards. To run it: php ./vendor/bin/php-cs-fixer fix.

4. Strict Typing

Strict typing in PHP helps control data types in functions and methods, increasing code reliability. All new methods and classes should be strictly typed, specifying exact types for parameters and return values.

Example:

Note: The declare(strict_types=1); declaration should be placed at the top of each file to enforce strict type checking and prevent type conversion errors.

5. Deprecation of Methods and Classes

Deprecated methods or classes in PrestaShop should be marked with a special annotation to inform developers about their planned removal in future versions.

Example:

6. JavaScript Code

For JavaScript files, PrestaShop recommends following Airbnb’s JavaScript style guide, which provides guidelines on code structure, naming conventions, and formatting. Use a linter to check code alignment with these standards: npm run lint-fix.

7. HTML, CSS (Sass), Twig, and Smarty

PrestaShop follows coding conventions for HTML, CSS, Twig, and Smarty developed by Mark Otto (creator of Bootstrap). The Stylelint tool analyzes style syntax and structure. To run it: npm run scss-lint.

8. License Blocks

All PrestaShop files should start with a license block detailing license information and usage terms, including core, theme, and module files. Example:

Following PrestaShop’s coding standards helps improve code quality and makes it easier to support and expand. Adopting a unified style, strict typing, and thorough documentation helps avoid errors, simplifies collaboration, and speeds up development.

What do you think of PrestaShop’s coding standards? Do you follow similar practices in your projects? Share your thoughts in the comments!