Hooks

Comments with description of hook functionality SHOULD NOT go into the hook comment. Instead, it SHOULD start just before a part of the code within hook implementation.

This is due to the fact that hooks are not generic functions, which are supposed to handle specific logic, but more of a wrappers or "gatherers" of another functions and business logic, each piece of which SHOULD have own definitive comments.

Incorrect

/**
 * Implements hook_form_alter().
 *
 * - Overriding some awesome fields because of super creative design.
 * - Handling summary visibility for different user roles.
 */
function MYMODULE_form_alter(){
  // code goes here
}

Correct

/**
 * Implements hook_form_alter().
 */
function MYMODULE_form_alter(){
  // Overriding some awesome fields because of super creative design.
  // code goes here

  // Handling summary visibility for different user roles.
  // code goes here
}

Please refer to RFC2119 for meaning of words MUST, SHOULD and MAY.

All donations are forwarded to Drupal Association.

Drupal is a registered trademark of Dries Buytaert.