Last updated 27 September 2014.

On this page:

To get help completing this task, see the Getting help completing your task page.

Goal

Review and improve the coding standards and documentation in a Drupal patch (software fix).

Skills needed

Ability to read and write clearly in English; some familiarity with PHP code.

Detailed steps

  1. Install Git on your computer, if it is not already installed. See the installing git page for more information.
  2. Find issues for a project. Choose an issue with the status "Needs Review" or "Needs Work."
  3. Look for the most recent patch file in the issue (the one attached to the most recent comment).
  4. Look only at the added or updated lines in the patch file (lines beginning with a +). Disregard removed lines (beginning with a -) or unchanged context lines (beginning with a space and no other character). You may wish to use dreditor or to download the patch file and read it in your text editor.
  5. Read all the added or updated inline comments (lines beginning with //, after the + sign and any indentation). Ensure that:
    • There is a space between each // and the comment text.
    • The lines are 80 characters or fewer (not including the + sign).
    • The text of the comments consists of clear, grammatically correct English sentences, each beginning with a capital letter and ending with a period.

    Make note of any lines that you think could be improved. (See the general documentation standards and inline comment standards for more information.)

  6. Every function and class added or changed by the patch should have a documentation header (docblock). Make note of any classes or functions that are missing a docblock. (A docblock begins with /**, ends with */, and has a * at the beginning of each line. See the documentation header standards for more information.)
  7. Read all the added or updated docblocks in the patch and ensure that they conform to documentation standards:
    • All lines should be 80 characters or fewer (not including the + sign).
    • All lines inside the docblock should begin with an asterisk (*) after the + sign and any indentation.
    • All function parameters and return values should be documented according to the function documentation standards.
    • Each docblock should begin with a one-line summary that begins with a third-person verb, unless the documentation standard specifies otherwise.

    Make note of any docblocks that you think could be improved. (For more information, review the Doxygen standards.)

  8. Next, review the PHP code in the patch and confirm that it follows all coding standards. Watch for whitespace errors in particular. Make note of any lines to clean up.
  9. At this point, if you have not found any lines that need to be fixed, add a comment to the issue indicating that you reviewed the patch code style and documentation and found nothing to improve. Move on to another issue.
  10. Otherwise, download the patch and apply it to your local Git repository.
  11. Open the files affected by the patch and fix the lines you noted earlier. Be careful to change only the lines that are already added or changed by the patch. Adding cleanups that are not a part of the patch makes the patch more difficult to review and increases the chance that it will "collide" with other issues. (If you notice documentation or code style errors in the file that are not already a part of the patch, you can file a separate issue to fix them.)
  12. Create a new patch with your improvements.
  13. Add a comment to the issue and explain what changes you made. Upload your patch as an attachment and set the issue status to "Needs Review" so that the patch is automatically tested by the Drupal.org testbots. It is also recommended that you upload an interdiff file showing your changes to the patch.

Screenshot of a comment with a cleaned-up patch and interdiff

Background and reference information

Next steps: moving beyond this task

  • Find another patch in the same project and improve its code style and documentation, following the steps above.
  • Read the PHP files for a project and create your own patch to clean up its code style and documentation.
  • Fix a Drupal core API documentation issue.

Notes for reviewers

In general, follow the instructions for contributing as a reviewer and how to review patches. Keep in mind how to give constructive feedback.

Specific to backporting patches:

AttachmentSize
cleanup_comment_interdiff.png17.17 KB