Coding Standards

Coding Standards

The Islandora project follows the Drupal coding standards for PHP files, which everyone is encouraged to read. Compliance is tested via Travis using CodeSniffer when a pull request is initiated or merged. We will not merge a pull request if Travis finds coding standard errors.

In order to make things easier, try to test your code with CodeSniffer before creating a pull request. There are also some great pages on the Drupal wiki about how to setup your favorite IDE.

Some quick links to various Drupal coding standards:

• PHP
• Javascript
• Links in translatable strings

Remember, to be consistent means using US spelling (e.g., "color" not "colour").

[TOC]

PHP Version

The minimum supported PHP version for Islandora is 5.3.3, which is loosely in line with the minimum version of PHP supported by Drupal. Code that does not run on PHP 5.3 and greater will not be merged.

Module Theming Guidelines

Much can be summed up about the benefits of coding for themers in the document Using the theme layer (Drupal 7.x) on drupal.org.

A well-made Drupal module allows all elements of its presentation to be overridden by the theme of the site on which it is used. In order for this theme layer to be usable, a module must be written to take advantage of it.

Guidelines to note:

• Strongly avoid explicitly printing HTML tags by using drupal API calls as much as possible. This will avoid unnecessary container usage, and help ensure your module's output fits with the enabled theme's look-and-feel. Whenever possible, the use of Drupal render arrays is encouraged.
• Use theme_table and theme_list functions where they make sense such as admin tables, etc. Otherwise use table/list markup in templates when there is a case for separating presentation from logic, such as search output and collection displays. Not everyone who wants to make simple markup changes to tables/lists is going to be a pro at wrangling pre-process functions, and we should not expect them to. Further reading: http://drupal.org/node/933976 Examples: Forum Lists in Drupal Core, Views grid layout, Island Scholar Solr Tables
• When using module css files, name/structure them properly. see CSS Cleanup (this applies to core and contrib modules)

CSS Best Practice

• Use tools such as CSSLint to check your css http://csslint.net/ (it will hurt your feelings, but help you code better)
• avoid inline css at all costs
• use lowercase letters and dashes to separate multiple word classes
• always prefix your module class names that are specific to the module with modulename-, or module-submodulename-
• class out fieldsets & fieldnames such as .islandora-mods-description
• use the semantic approach to naming, like classes that illustrate a certain meaning of the element such as .main and .sidebar-one as opposed to presentational or structural naming methods like .right-bar .left-content
• utilize standard classes drupal uses, such as .odd, .even, .clearfix, .title, .element-invisible, .element-hidden, .tabs (see all of the system.*.css files in d7/modules/system/ for available class names)
• use multiple css selector classes in the same element, both generic and specific.. example panels/view output <div class="panel-pane pane-views pane-slideshow">...</div>

Documenting Islandora interaction with Fedora

Whenever we interact with Fedora in the comments using either:

• @throws
• @return

we need to document what is returned on error and what state the Fedora is left in, so that the error can be reported through Drupal instead of failing silently and whoever is calling the API can make a choice about what to do next.

Islandora Module File Structure and Naming

tl;dr: Filenames should contain lowercase characters and PHP files (except templates) should use underscores to separate words in the filename.

Why define a naming convention, specifically for Islandora Drupal development?

Consistent file naming augments the ability of developers to quickly identify the location of code within modules. The Drupal community has not documented a set of conventions related to naming files although a pattern of file naming can be observed by reviewing major contributed modules.

Modules Conventions

Modules meant for public distribution are generally expected to include a README.txt and LICENCE.txt file. README.txt files should follow the Drupal README.txt conventions found here (https://drupal.org/node/2181737). Due to our heavy use of github we will be using README.md files to take advantage of their markdown parsing on repository landing pages.

Conventions for PHP files

PHP code will generally be placed in (.module, .install, .test, .inc, .php) files. Unless otherwise specified, file names should contain only lowercase characters and should use underscores to separate words in the filename.

Good: islandora_something.inc   Bad: IslandoraSomething.inc

Module Files (*.module)

Hook implementations and functions providing API-like interfaces or extensively used utilities should be placed in the .module file of a module. Typically, it is expected that if this module is part of the islandora ecosystem (meant for wide distribution and to be branded as part of islandora) the module's name will begin with islandora.

Include Files (*.inc)

Include files (/*.inc) should contain all other PHP code (not relating to theming or installation) and should be placed in a subdirectory of the module named /includes/. The module name should not be used as a prefix in the filename; it is redundant. These rules apply to all .inc files, including files containing classes. To further aid file discovery, include files may contain a file-type extension helper such as .form or .pages if the file contains menu callbacks grouped together (example: admin.form.inc).

Good: includes/mime_detect.inc    Bad: includes/islandora_mime_detect.inc

Good: includes/upload_form.inc    Better: includes/upload.form.inc

Template Files (*.tpl.php)

Template files should have an extension of .tpl.php and should be placed in the theme subdirectory of the module. Template filenames should include the theme name with words separated by a hyphen/dash (example: islandora-object.tpl.php).

The theme subdirectory can also contain files like theme.inc or *.theme.inc, where any theme related functions can be implemented (preprocess theme hooks, etc). Functions included in *.theme.inc files should only be used by the theme system, if a function is used elsewhere it should be moved to a different file.

Good: theme/module_name.theme.inc    		Bad: includes/theme.inc

Good: theme/islandora-object.tpl.php     	Bad: theme/islandora_object.tpl.php

Meaningful Locations of PHP/Module Files

The following table summarizes where files are expected to be.

Subdirectory      Files

/                 *.module, *.info, *.api.php, *.install

/includes         *.inc

/theme            *.tpl.php, *.theme.inc

/tests            *.test, (Any related test files, regardless of extension)

Non PHP-Files

General purpose subdirectories may be used for related files of a similar mime type or purpose, such as images (example: *.png or *.tiff files in ../images). Unless otherwise specified filenames should contain only lowercase characters and should use underscores to separate words in the filename.

Subdirectory    Extensions

/css            *.css

/js             *.js

/images         *.jpg, *.tiff, *.png, etc

CSS files (*.css)

Modules should always prefix the names of their CSS files with the module name; for example, system-menus.css rather than simply menus.css. Themes can override module-supplied CSS files based on their filenames, and this prefixing helps prevent confusing name collisions for theme developers. See drupal_get_css() where the overrides are performed. Also, if the direction of the current language is right-to-left (Hebrew, Arabic, etc.), the function will also look for an RTL CSS file and append it to the list. The name of this file should have an '-rtl.css' suffix. For example, a CSS file called 'mymodule-name.css' will have a 'mymodule-name-rtl.css' file added to the list, if exists in the same directory. This CSS file should contain overrides for properties which should be reversed or otherwise different in a right-to-left display. CSS files

can use dashes to separate words as well as underscores.

Good: css/islandora_admin.css    Bad: css/IslandoraAdmin.css

Good: css/islandora-admin.css    Better: css/islandora.admin.css

References

Please refer to the Module documentation guidelines For more information on conventions.