Blog/ Code quality guidelines for large Drupal projects

By neerav.mehta Tue, 04/28/2015 - 02:00 Comments

Are you wondering what code quality guidenlines your Drupal developers should follow in addition to Drupal's coding standards to make the code readable, secure and performant? What are the best practices so that developers can follow each other's code easily and make code review faster?

Here are the guidelines you should follow in addition to the Drupal coding standards. Note that we use PHPStorm as our editor so some of our guidelines are based on what it does. Please adjust these recommendations based on the editor you are using.

1) Use of t() function is mandatory otherwise it is a security risk. It also helps if the you want to make the site multilingual at some point of time. Make sure to always use it. Note that in hook_menu(), the title value should not use t() function since it passes through t() function later automatically.

2) If you are getting values from a form, make sure to use check_plain() otherwise it is a security risk.

3) Each function should start with a phpdoc style comment (starting with /**) about what the function does. Write input parameters as well as return parameter in the comment. PHPStorm gives a warning if the phpdoc comment doesn't match the function structure. Do not ignore it.

4) If function is a hook, write "Implements hook_{name}". There is no need to write arguments and return arguments in comment then. For e.g.

/**
 * Implements hook_menu().
 */

For hook_form_FORM_ID_alter(), add which form you are altering. For e.g.

/**
 * Implements hook_form_FORM_ID_alter() for user_register_form().
 */

5) All the variable names that you define have to be meaningful. For e.g. use $old_category_name instead of $val. A person reading your code should know what that variable stores. Also, if a variable has two words in it, use "_" to separate them. For e.g. do not use $memberid. Use $member_id instead. PHPStorm does spellcheck automatically. There is no reason to use a variable name with wrong spelling, unless it is something related to Drupal. For e.g. PHPStorm gives spelling warning on $nid, which we are fine to use since it has direct connection to Drupal.

6) Any one function should not be more than 50 lines long including spaces. If it is long, then create sub-functions. In some cases, the function will be more than 50 lines long and that's fine. Just be prepared to justify that why it needs to be so long.

7) Use meaningful names for functions. Separate words in a function name by "_". For e.g. instead of using "search_relatedmembers_display", use "search_related_members_display".

8) .module file should contain only hook implementations. For e.g. hook_init(), hook_menu(), hook_preprocess_node(), etc. .module file can also contain form's validate and submit handlers. All other functions that are not hooks should be in separate files. This will reduce page load times. Separate files you create should have logical structure based on which functions will get loaded simultaneously in a function call. For e.g. when I am searching users, I will not be needing functions related to content search search. So include user search related functions in a separate file which will be loaded only on user search page using hook_menu() or module_load_include(). If a function is shared between multiple files, write it in a common file such as <module-name>.common.inc and include it using module_load_include() function. Before you move any function to a file outside .module file, use Edit -> Find -> Find Usages in PHPStorm to see which other modules/files is using this function. You will need to use module_load_include() in these files so that the code does not break.

9) When you commit code via PHPStorm, it shows you a list of errors and warnings. A lot of warnings are that $form, $form_state are not used, etc. These are fine. But you should take warnings and errors such as "variable may not have been defined" seriously and remove them.

9) PHPStorm menu has Code -> Locate Duplicates. Use "Locate Duplicates" for searching code duplicates in custom modules folder. If there is significant and logical duplication, then create a function out of it and use it.

10) If you find that two functions are doing the same thing except for minor changes which can be handled using arguments, create a function with arguments and use that.

11) If you are querying for entities, use Entity Field Query. For every other query, use dynamic queries. Do not use db_query() since the query you write may not be applicable to all the database types and you may need to change them if database type changes in future.

12) Always use LANGUAGE_NONE instead of 'und'.

13) When you are getting value(s) of fields from node or entity, use field_get_items() instead of getting the items using $node->field[LANGUAGE_NONE][0]['value]. The advantage of field_get_items() is that it takes care of getting the items in the correct language, which can be useful later in case the client wants to create a multilingual site.

14) Template files should not have any logic except "for" and "if" statements. Put any logic in preprocess or process functions. Code execution in preprocess or process functions is much faster than in template file.

If you have some other guidelines that you follow in addition to the above, please write them in the comment below. Want to know more about Drupal development and how to create and manage large Drupal sites? Subscribe to our weekly newsletter!

 
Ready to get started?REQUEST A QUOTE