Developer guidelines
Coding standards
The coding guidelines for arbit are described below. All code has to be written with error reporting E_ALL | E_STRICT | E_DEPRECATED.
Braces
-
Curly braces are always put in a new line on the same level of the line above.
-
Opening parenthesis are always followed by a space, if there is some content between the parenthesis, and closing parenthesis are always preceded by a space.
-
Each statement must be followed by a space, no method name may be followed by a space before the opening parenthesis.
-
There are no special spaces around square brackets.
class blubb
{
function foo()
{
if ( false )
{
return $array['bar']
}
}
}
Files
-
You may only use lowercase alphanumeric characters and underscores in file names. Only the pure extension ".php" may be used for PHP files.
-
Template files always use the extension ".tpl".
-
-
Each file starts with a file level docblock including the license and a very short description of the files purpose.
-
There must not be a closing ?> in files.
To be discussed
-
There must not any author or copyright statement in the source files.
Documentation
-
Each class, method and function (private, public or protected) must include a full docblock including a description of the purpose, parameters and return values.
-
Complex algorithms or implementation should be described in-depth in the class or method headers.
-
You are free to include inline documentation and @TODO: comments inside the source, but they should normally only be used for non trivial statements.
General formatting
-
You should try not exceed a common line length of 85 characters, but this is not a hard limit, as long class names may require more characters.
-
You should try to wrap method parameters and multiple values in arrays to improve general readability.
-
You should always include a dangling comma in arrays, especially when exceeding one line, to reduce the patched lines, when adding values to the array later.
Naming
-
Class and method names are all formatted camel case.
-
Avoid names which does not give additional meaning or are unclear.
-
The order of class name elements does NOT need to represent the directory hierarchy, eg. a arbitCoreController may be located at arbit/controller/core.php.
-
Never use abbreviations for variable names or methods, except they are really well known, like "HTTP".
Commit messages
We have very strict rules for commit message formatting, which provides us with a basis for automatic parsing and generating of reports.
All messages should wrap at 79 characters per line. This means, if you are writing multiple lines after a message starting with a "- " each following line should be indented by exactly two spaces.
Including descriptive text in your commit messages is generally important to offer a good overview on the commit when the issue tracker is not available (commit mails, history).
All messages may include references to existing issues to add status updates to the issue, which should look like:
- Refs #<number>: <text>
Where <number> references the ticket and the <text> describes what you did.
Comments
You may always append arbitrary comments in your commit messages, where each line should start with a number sign (#). Text in these lines won't be checked.
Bug fix
A bug fix commit message should follow the following scheme:
- Fixed #<number>: <text>
Where <number> references the closed bug and <text> is a description of the bug and the fix. Keep in mind that the texts will be used for the changelog, so please check the spelling before committing.
The bug number is not optional, which means that there should be an open bug in the issue tracker for each bug you fix.
For compatibility with other issue tracker you may also use "Closed" instead of "Fixed" in your message, but "Fixed" is highly preferred.
New features
If you implemented a new feature, your commit message should look like:
- Implemented[ #<number>]: <text>
Where <text> is a short description of the feature you implemented, and <number> may optionally reference a feature request in the bug tracker. Keep in mind that the texts will be used for the changelog, so please check the spelling before committing.
Documentation
If you extended your documentation, your commit message should look like:
- Documented[ #<number>]: <text>
Where <number> optionally specifies a documentation request, and the text describes what you documented.
Additional tests
If you added tests for some feature, your commit message should look like:
- Tested: <text>
Where <text> describes the feature(s) you are testing.
Other commits
If your commit does not match any of the above rules you should only include a comment in your commit message or extend this document with your commit message of desire.
Grammar
The grammar for commit messages is defined as:
Message ::= Statement+ | Statement* Comment+ Statement ::= Reference | Fixed | Implemented | Documented | Tested Comment ::= '# ' TextLine | '#\n' Reference ::= '- Refs' BugNr ': ' TextLine Text? Fixed ::= '- ' FixedString BugNr ': ' TextLine Text? Implemented ::= '- Implemented' BugNr? ': ' TextLine Text? Documented ::= '- Documented' BugNr? ': ' TextLine Text? Tested ::= '- Tested: ' TextLine Text? FixedString ::= 'Fixed' | 'Closed' Text ::= ' ' TextLine Text? BugNr ::= ' #' [1-9]+[0-9]* TextLine ::= [\x20-\x7E]+ "\n"
With one additional condition not mentioned in the grammar, that no line should ever exceed 79 characters per line.