Skip to content

Commenting

Jump to bottom Edit New page
zenmiu edited this page Aug 5, 2011 · 2 revisions

General requirements

Required:

  1. In comments, always use the auxiliary tags from the PHP Documentor system [REQ.PHP.4.1.1].

  2. Only С comments and С++ comments are allowed; other comments are not allowed [REQ.PHP.4.1.2].

  3. A multi-line comment should be formatted as follows:

    • The first line of the comment contains only the '/**' sequence (opening comment tag followed by an asterisk) [REQ.PHP.4.1.3].
    • All lines, except the first and last, begin with the ' * ' sequence (a space character followed by an asterisk followed by another space character) [REQ.PHP.4.1.4].
    • A comment ends with ' */' (a space character followed by the closing comment tag) [REQ.PHP.4.1.5].
    • All lines of a comment must have the same level of indentation [REQ.PHP.4.1.28].

  4. A comment should stand close to the commented block of code or object [REQ.PHP.4.1.6].

  5. A multi-line comment must not contain any extra blank lines in the beginning of the comment [REQ.PHP.4.1.7].

  6. PHP Documentor tags and their values must be lined up [REQ.PHP.4.1.8].

  7. PHP Documentor tags must follow the order (regardless of their availability) [REQ.PHP.4.1.9]:

  • Category
  • Author
  • Copyright
  • License
  • Version
  • Link
  • See
  • Since
  • Deprecated
  1. Several identical PHP Documentor tags in one comment should be grouped together and go in a succession. [REQ.PHP.4.1.10].
  2. The value of the category tag should be formatted according to the Pascal Casing standard with underscore used for the word delimiter [REQ.PHP.4.1.11].
  3. The tags should be declared as described in the documentation to PHP Documentora [REQ.PHP.4.1.12].
  4. Tag format:
  • A block of param tags should be separated from other tags with a blank line [REQ.PHP.4.1.20].
  • A block of param tags should appear first among other tags [REQ.PHP.4.1.21].
  • The argument type in a param tag should be separated from the tag name by 1 space [REQ.PHP.4.1.22].
  • Argument names in param tags should be aligned to one another [REQ.PHP.4.1.23].
  • Argument comments in param tags should be aligned to one another [REQ.PHP.4.1.24].
  • Tag values must properly pass the properties of the commented object (e.g., function argument types) [REQ.PHP.4.1.25].
  • A param tag must contain argument type, its name, and a comment to it [REQ.PHP.4.1.26].
  • A block of param tags must describe all the arguments [REQ.PHP.4.1.27].
  1. Comment text must be separated from a block of tags with a blank line [REQ.PHP.4.1.18].
  2. Text blocks (brief and full description) must be separated with a blank line [REQ.PHP.4.1.19].
  3. No tag values/comments may have the format of "xxxxx". This format is reserved to the default values, automatically inserted by PhpCodeDocumentator [REQ.PHP.4.1.20].

Recommended:

  1. Comments should be meaty. Think of comments as a description of your system. Be prepared that your comments will be extracted from the source code and published as a manual. Comments to the classes will be one part of the manual, method signatures - the second part, method arguments - the third part, and method implementations - the fourth part of the manual. All these parts should merge into an organic whole and inform user, remote in space and time, of what you have done and why.
  2. Document your decisions. Comments should documents the decisions you make. Every time you choose a certain implementation method, place a comment telling what you have chosen and why. That will be the most useful information for archaeologists.
  3. Clearly indicate “gotchas” [“traps” in the code].
  4. Comment both any variable changes, not fitting the normal course of the program, and all the constructions that could make balls of the program if the code changes. For an explicit reference to problematic or potentially problematic pieces of code, use the internal reserved words.

Using Gotchas

Required:

  1. When using gotchas, use the appropriate reserved words [REQ.PHP.4.2.1].
  2. A key word gotcha must follow the description in the comment and be separated from the description with a blank line [REQ.PHP.4.2.2].
  3. Comments with gotchas must be separated from other blocks of comments with a blank line.
  4. If a comment contains a link to a ticket in Bug Tracker, that link should be placed at the beginning of the comment and have one of the following formats [REQ.PHP.4.2.4]:
  • [M:], where id - tictket ID in the internal Bug tracker
  • [E:], where id - tictket ID in the external Bug tracker
  • [S:], where id - user story ID in ScrumNinja
  • [G:], where id - ticket ID in github’s Issues

Recommended:

Internal reserved words are used for an explicit reference to problematic or potentially problematic pieces. Keep in mind that the robot will parse your comments by keyword, classify them and generate a report, so that others could take an appropriate action where it is necessary.

Reserved words for describing gotchas:

  • TODO: comment — indicates a place that requires a revision; simple reminder.
  • FIXME: comment — indicates a place with a discovered error; give the description and (optionally) ID of the error.
  • KLUDGE: comment — if something you have done looks or works ugly, indicate that fact and explain how you are going to do it next time when you have time.
  • TRICKY: comment — message that this piece of code is very hard to go around, and therefore one should not change anything in it unless have understood all the "intrigues" of the design.
  • WARNING: comment — warning about something.
  • PARSER: comment — sometimes you have to do something for successful parsing. Document that fact. Perhaps, with time the problem will disappear.

Example:

/**
* TODO: [M:1234] performance problems may occur

/**
* KLUDGE: potentically unsafe behavior of the type

Commenting file

Required:

  1. Each file begins with a header, which consists of:
  • Single-line comment with directives for vim (vim: set ts=4 sw=4 sts=4 et:) in the form of a one-line comment [REQ.PHP.4.3.5].
  • Docblock comment with product name, license and the following attributes in the PHPDocumentor format [REQ.PHP.4.3.7], [REQ.PHP.4.3.2], [REQ.PHP.4.3.4], [REQ.PHP.4.3.9]:
    • Minimum PHP version, as PHP version x.y.z. The version may not be less than 5.3.0 [REQ.PHP.4.3.3].
    • @category with category LiteCommerce
    • @author with Creative Development LLC info@cdev.ru [INTERNAL]
    • @copyright with Copyright (c) 2010 Creative Development LLC info@cdev.ru. All rights reserved [INTERNAL]
    • @license with http://opensource.org/licenses/osl-3.0.php Open Software License (OSL 3.0)
    • @link with http://www.litecommerce.com/ [INTERNAL]
    • @see with the link to the page with the the documentation file
    • @since with the version of core or module when the file appeared for the first time
  1. Tags @category, @copyright, @license, @link, @see, @since are to be singular [REQ.PHP.4.3.8].
  2. Tag @author is to be singular [REQ.PHP.4.3.8] [INTERNAL].

Example:

<?php
// vim: set ts=4 sw=4 sts=4 et:

/**
* LiteCommerce
*
* NOTICE OF LICENSE
*
* This source file is subject to the Open Software License (OSL 3.0)
* that is bundled with this package in the file LICENSE.txt.
* It is also available through the world-wide-web at this URL:
* http://opensource.org/licenses/osl-3.0.php
* If you did not receive a copy of the license and are unable to
* obtain it through the world-wide-web, please send an email
* to licensing@litecommerce.com so we can send you a copy immediately.
*
* PHP version 5.3.0
*
* @category   LiteCommerce
* @author     Creative Development LLC <info@cdev.ru>
* @copyright  Copyright (c) 2011 Creative Development LLC <info@cdev.ru>. All rights reserved
* @license    http://opensource.org/licenses/osl-3.0.php Open Software License (OSL 3.0)
* @link       http://www.litecommerce.com/
* @see        ____file_see____
* @since      3.0.0
*/

Commenting class

Required:

  1. Each class must have a block of comments [REQ.PHP.4.4.1].
  • The block includes:
  • A comment describing the class [REQ.PHP.4.4.2].
  • PHP Documentor's mandatory tags: see and since [REQ.PHP.4.4.3].
  1. Only C comments are allowed for commenting classes [REQ.PHP.4.4.5].
  2. All PHP Documentor’s tags are to be singular [REQ.PHP.4.4.6].
  3. PHP Documentora’s tags that may be used in comments: see, since, deprecated [REQ.PHP.4.4.7].

Example:

/**
* Application singleton
*
* @see   ____class_see____
* @since 3.0.0
*/

Commenting functions and class functions

Required:

  1. Each function must have a block of comments [REQ.PHP.4.5.1].
  2. The block includes:
  • A comment describing the function [REQ.PHP.4.5.2].
  • PHP Documentor's mandatory tags: param (if arguments are present), return, see, since [REQ.PHP.4.5.3].
  1. Only C comments are allowed for commenting functions [REQ.PHP.4.5.6].
  2. All PHP Documentor’s tags are to be singular, except param and throws [REQ.PHP.4.5.7].
  3. Comments to arguments and methof output begin with a capital [REQ.PHP.4.5.8].
  4. Tag throws becomes mandatory if an exception is dropped inside the method [REQ.PHP.4.5.3].

Example:

/**
* Set controller
*
* @param mixed $controller Controller OPTIONAL
*
* @return void
* @see    ____func_see____
* @since  3.0.0
*/
public function setController($controller = null)
{
}

Commenting class variables

Required:

  1. Each class variable must have a block of comments [REQ.PHP.4.6.1].
  2. The block includes:
  • A comment describing the variable [REQ.PHP.4.6.2].
  • PHP Documentor's mandatory tags: var, see, since [REQ.PHP.4.6.3].
  1. Only C comments are allowed for commenting variables [REQ.PHP.4.6.4].
  2. All PHP Documentor’s tags are to be singular [REQ.PHP.4.6.5].

Example:

/**
* It is testId :)
*
* @var   integer
* @see   ____var_see____
* @since 1.0.0
*/
protected $testId = 1;

Regulations on using type names in describing methods and properties:

Required:

Preference is given to the full type names [REQ.PHP.3.5.15] [!]:

  • integer (replaces int)
  • float
  • string
  • array(type)
  • mixed (if more than 4 types available)
  • void (only as an indicator that the function does not return any values or does not have a return)
  • object (use only when you REALLY use ANY object of ANY class)
  • boolean (replaces bool)
  • resource
  • callback (this includes the string with the function name, the array object-method_name and the object of the \Closure class)

Examples:

* @param integer              $value New value
* @param array(mixed)         $value New value
* @param \XLite\Model\Product $value New value
* @param boolean              $value New value

* @return void

If several types are accepted or returned, they are listed via the pipe (|) sign, no spaces, but not more than 4 in a row [REQ.PHP.3.5.17].

Example:

* @param integer|string $value New value

If a method argument is optional, terminate its description with the auxiliary word OPTIONAL [REQ.PHP.3.5.18].

Example:

* @param integer $value New value OPTIONAL

Commenting method / property blocks

Allowed comments are those that separate different method / property blocks. They are formatted as regular comments followed by a folding opening sequence (// {{{ ) and a brief description of the block. The block is closed using the comment tag followed by a folding closure sequence (// }}}). Such comment is separated with a blank line at the top and at the bottom.

Example:

// {{{ Calculation

public function getId()
{
   ...
}

// }}}
Add a custom footer
Add a custom sidebar
Clone this wiki locally