The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
Documentation is important because you are always working as a team, even if that team is only you and your future self. This guide addresses the minimum requirements for API documentation (DocBlocks) and style guides for inline commenting.
DocBlocks MUST start with /**.
Intermediate lines within a DocBlock must begin with * (first character is a real space).
DocBlocks MUST end with */ (first character is a real space).
Each PHP file MUST include a file Docblock at the head of the file, on the next line after the opening <?php tag.
A @license tag MUST be provided.
A @copyright tag MUST be provided.
Each class MUST include a Docblock immediately before the class definition statement.
A @since tag SHOULD be provided.
Each class property MUST include a DocBlock immediately before the property or constant definition statement.
A @var tag MUST be provided.
A @since tag SHOULD be provided.
Each function or class method MUST include a Docblock immediately before the function/method definition statement.
A @param tag MUST be provided for each argument in the function/method.
A @return tag MUST be provided.
A @throws tag MUST be provided if the function/method throws an exception.
A @since tag SHOULD be provided.
Ideally, code should be written to be read without the need for additional inline comments. However, inevitabilty they are necessary.
When commenting inline, C style comments (/* */) or standard C++ comments (//) MUST be used.
Perl/shell style comments (#) MUST NOT be used.