Coding standard draft for the Doctrine project

coding-standard.md

• Code must follow PSR-2.
• Classes must have a docblock documentation describing their purpose.
• Class methods must have a docblock documentation, in this order:
  • A mandatory one-line short description.
  • An optional multi-line long description.
  • A mandatory @param annotation for each parameter: @param [type] [name] [description]
    • [type] is the type of the variable, primitive or class.
    • [name] is the name of the parameter, including the leading $.
    • [description] is a short description of the parameter. If the description spans multiple lines, all lines must be indented by the same number of spaces as the first line.
    • The indentation must be such as types, names and descriptions for all parameters of a single method start on the same column.
  • A mandatory @return annotation: @return [type] [description]
    • [type] is the return type, primitive or class.
    • [description] is an optional short description of what the method returns.
    • If the method does not return anything, this must be explicitly documented as @return void.
  • One or more @throws annotations if the method throws any exception.
• Class properties must have a docblock documentation, in this order:
  • A mandatory one-line short description.
  • An optional multi-line long description.
  • A mandatory @var annotation: @var [type].
    • [type] is the variable type, primitive or class.
• The following rules apply to any docblock documentation:
  • Primitive types must be lowercase and use the following forms:
    • integer, not int.
    • boolean, not bool.
    • float, not double or real.
  • Classes must use the Fully Qualified Class Name.
  • If a variable can contain multiple types, it must document all types, separated by a | vertical bar.
  • If a variable is of type array, but only contains objects of a certain type, it should be documented as ClassName[], not array.
• All elements of different types in a docblock must be separated by an empty docblock line (short description, long description, annotations of different types).
• return statements must be separated from the previous statement by an empty line, unless they come right after an opening bracket.
• Class properties that are null by default must not declare a default = null; value.

We currently have one thing that doesn't follow PSR I think, which is:

if ( ! $condition) {
}

Indeed, I think PSR advocates it as if (! $condition) {.
Wouldn't it be better not to remove bits of PSR, and just convert the existing codebase to this standard?

@BenMorel can you add the null type to the docblock documentation? I think the ClassName[] syntax should also be used for traversables.

Also to be noted:

• Assignment operations of a logical group should have the = sign aligned.
• Different logical blocks (not necessarily delimited by { or }) should be separated by an empty line

@Ocramius Regarding null, do you mean in this sentence: Primitive types must be lowercase and use the following forms? I've only mentioned the ones that can take multiple forms. This excludes null, but also array, and resource. Do you think that's confusing?

Also, how can we define a logical group?