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.


 * How to use 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.

The coding conventions described in this document are also general. They apply mostly to most of the packages in the Wikibase codebase and closely associated projects. Some packages do not follow a specific guideline, which can be by design, or due to legacy reasons. One should carefully consider diverging from policies adhered to in these packages even if they conflict with the ones outlined here. If the package specific documentation does not provide more information on these divergences, it is recommended you contact the package maintainers for more information.

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 code 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.

@since tags
@since tags indicate in which version the annotated artifact has been introduced. This is important for people building on top of a codebase and want to provide compatibility with more then the latest development version.

As with all manually maintained information in comments, these tags come with a cost. They are clutter to a lot of people that have no use for them, and they have the potential to be wrong. It is therefore discouraged to add these tags to all classes and methods.

Adding @since tags for protected or private methods serves little purpose. The same goes for adding these tags to classes or interfaces that are private to a package. Public classes and interfaces, as well as the public methods defined in them, likely deserve an @since tag. This is especially true if the interfaces these are part of are expected to be relied upon by many users, as is for instance the case in libraries.

Referring to resources in other namespaces
Code inside classes should generally not contain any fully qualified names, and rather import the needed classes or interfaces.

Wrong:

Right:

Usage of relative references is also discouraged.