Wikibase/Coding conventions

This page describes the coding conventions used within the wider Wikibase codebase. This includes code formatting policies, high level architecture recommendations and everything in between.

A good portion of the Wikibase code is part of MediaWiki extensions, and almost all of the code has been written to support these MediaWiki extensions. As a result the guidelines used are based on the MediaWiki coding conventions, in particular the ones that apply to PHP and JavaScript. This document outlines the additions and modifications compared to these guidelines. In other words, you should generally follow the MediaWiki coding conventions unless they are contradicted by this document.

It is also important to consider that the more complicated the subject of the guideline, the more you are recommended to use critical thinking and not blindly apply said guideline. To be concrete, simple things such as code formatting should be viewed as policies and strictly adhered to in almost all cases. Subjects such as component design have a set of applicable recommendations, and rules that should generally be followed. Those rules will of course not always apply, and almost always still require one to make informed tradeoffs. Good design cannot be achieved by mindlessly applying rules.

Documentation header
The MediaWiki coding guidelines on this topic state one should use a verbose GPL header. Our policies state the opposite and strongly discourage inclusion of such verbose headers.

The general idea behind our policy is that only documentation relevant to developers should be included. Everything else is clutter that gets in the way. When someone opens a file, you do not want them to have to always scroll down first before they can actually see the relevant code. The cope is more important then the address of the Free Software Foundation.

This means the following things should NOT be included:


 * The verbose GPL header
 * @file tags, either with or without file name
 * Any @ingroup or @package tags - organization is already done by the directory structure and namespaces
 * Any dates or other crust your default IDE template might contain

Things that need to be included:


 * @license tag
 * @author tag (there can be multiple)

Other things that are often included:


 * @group tag in tests
 * @since tag for public classes and interfaces
 * Any documentation the class or interface requires

Namespace, imports and newlines
Formatting should furthermore follow the above example. This means having the following sections, each separated with a newline:


 * The PHP opening tag
 * The namespace your class resides in
 * Any use statements to import resources from other namespaces
 * The class documentation header directly followed by the class declaration

The namespace declaration and the use statements all use fully qualified names that do not start with a backslash.