The Drupal Commerce project is striving for strict adherence to the following development standards to produce the best quality code we can with a high level of maintainability. Any patch that is posted for review will be subject to these standards, which largely follow widely accepted Drupal development standards. Some of these items are simply best practices that will help us have a unified code style throughout the project.
If a patch needs work based on any of the project's development standards, please indicate the number below so the patch author can adapt his or her code style.
Suggestions for improving and/or expanding these standards should be posted in the Brainstormings forum for consideration. Don't be shy... we want these to be as helpful as possible.
We'll follow Drupal's coding standards for code syntax and documentation. All functions should be well-documented with both doxygen comment blocks and inline comments. Patches should pass the code review provided by the Coder module.
Modules should pattern their files and directories after CCK:
example.info
example.module
README.txt
/help
/includes
/includes/example.pages.inc
/includes/example.admin.inc
/includes/views
/includes/views/handlers
/tests
/theme
/theme/theme.inc
/theme/example.css
/theme/example-foo.tpl.php
The help directory contains files compatible with the Advanced Help module. The includes directory contains files referenced in menu items and other necessary module includes. The theme directory contains a theme.inc file for theme functions and preprocess functions in addition to any CSS or module based .tpl.php files. Theme / preprocess functions referenced by functions in .admin.inc and .pages.inc files can reside in the files themselves.
The tests directory contains SimpleTest include files.
Module .info files should use a strict set of package names:
As an example exception, Commerce PayPal uses the Commerce (PayPal) package name, because each PayPal payment method is represented by a separate module that depends on a core PayPal module for IPN processing. It is helpful to the user to group these 4+ modules together with their dependency.
Contributed modules that don't conform to this standard should not be included in Features / distributions until they do. Issues should be posted on drupal.org to projects that do not conform.
Use the [module]_(object)_verb pattern for all function names:
commerce_product_load()
commerce_product_type_load()
(This list of examples needs to be fleshed out further.)
Hooks should include a soft namespace by using the commerce_ prefix to avoid conflicts with other contributed modules. For example, Ubercart's hook_order() would become hook_commerce_order() under this convention.
Only form builder functions should end in _form.
We will be using Drupal 7's core SimpleTest testing framework to facilitate code development and maintainability. While not embracing true test-driven development, we will still only be committing code that comes with appropriate function tests.
The Commerce module provides a base class used for creating Drupal Commerce tests. The process is documented in the Specification handbook, Writing SimpleTests for Commerce modules.
Unit testing is under consideration for the core APIs, but a realistic target for now is to mimic Drupal's core test coverage guidelines.
Drupal Commerce modules should follow Drupal coding best practices when implementing core APIs, including (but by no means limited to):
Our general rule is to integrate with major, well-maintained third party modules where possible. For example, Drupal Commerce modules should depend on Views instead of creating their own table listings. Ctools and Panels integration are under consideration, pending availability on Drupal 7.
Our problem in the past has been too few permissions, not too many. In general, we're adopting an approach that favors finer-grained permissions over having too few. Every permission should have a description.
This same goal holds true for access control as it pertains to products, orders, customer profiles, etc. While the core modules don't need to anticipate every possible implementation of the Commerce modules, these access systems and others like them should be extensible to allow for finer-grained access. The goal here is to eliminate the need for core patches to allow use cases like peer-to-peer sales.
In Ubercart we provided numerous configuration options to override interface strings, like the text used on the Add to Cart button. This presented a problem for multilingual sites, as Drupal's localization system can translate string literals but not variables. (For more information, see documentation on the t() function.)
To correct this problem, the ability to override strings via custom settings forms will not be provided by the core modules. Instead, we will instruct administrators to use the String Overrides module (or whatever comparable systems exist).
Furthermore, modules should provide help 'context' to functions used in localization to facilitate accurate translation.
Module files and includes should not contain style tags or attributes in any HTML output. Instead, use appropriate IDs and classes with coordinating CSS in the module's .css file(s).
Template files with preprocess functions should be used for nearly all HTML output. In cases where logic cannot be easily abstracted into variables in preprocess functions or when the amount of HTML is very minor, a theme function can be used instead. Use Drupal's core theme functions whenever possible.
As much as possible, we want to enforce at the core level a strict separation of API components from UI components. At one level, this looks like including both a dc_product and dc_product_ui module, like the core Drupal field and field_ui modules. Since a major goal of the project is to develop a solid core and leave the door open for installation profiles and Feature modules to take care of packaging components, we don't want to make it difficult for developers and site builders to replace default UI components.
To be honest, we could probably use a separate set of user interface guidelines to ensure we have a consistent feel across all the Drupal Commerce modules.
Code should take advantage of static caching and *_load_multiple() API functions to reduce the amount of queries per page request. The Code module can also be used to audit queries for execution speed. Code should also take advantage of Drupal's file handling abilities in various systems (like the #file property on menu items) and class autoloading capability to minimize the amount of code loaded on any given pageload.
A topic for discussion would be a custom variable storage table or system to reduce the amount of variables stored at the global level. At the very least, modules should consider storing data in custom tables before storing complex module settings in Drupal's variables system.
If there's anything we've learned from our past, it's that we want to leave serialized arrays of data in the database behind. We're striving for better data models, and this section should be fleshed out as the project matures.
This heading could be further expanded to address all of our underlying data models and how to best incorporate classes in our modules.
Found errors? Think you can improve this documentation?
edit this page