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.

Tests
In general we apply the policy that all new behaviour should be tested. There are exceptions for trivial code, such as getters and setters, in particular when the code is not expected to be widely dependent upon. Tests will make it easier for yourself to ensure your code is correct (testing through the user interface takes a lot more effort and is less effective), and will get your code through review quicker.

Use mocks where appropriate. (PHPUnit mocking docs)

Most code should have real unit tests (that just test the unit of code) rather then component, integration or system tests. When writing a test that falls in one of the later categories, keep it separate, so people can run all unit tests without needing to wait for some database or network.

Comments

 * Prefer clean code over bad code with comments


 * "When you feel the need to write a comment, first try to refactor the code so that any comment becomes superfluous." -- Martin Fowler, Refactoring: Improving the Design of Existing Code, 1999

Generally try to avoid comments. Only add those that are really needed, and cannot be made superfluous by making the code itself more clear.


 * Avoid redundant comments

The comments here do not add any value. They therefore should be omitted.

This is much better:


 * Comments themselves should be clean

When running into a situation where a comment is needed, take care to write a short and precise comment that has correct grammar and punctuation.


 * Keep in mind the cost of comments

Comments are prone to being inaccurate, and tend to become more inaccurate over time, as code gets updated, while the comments do not. Unless great care is taken, comments will end up spreading disinformation, often subtly. At point they hurt more then helping. In this regard every comment is a liability.

Class design
The SOLID principles should be kept in mind and generally adhered to.

Package design
The package principles should be kept in mind and generally adhered to.

One class per file and PSR-0
For code organization on class and file level, we generally follow PSR-0.

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.

JavaScript style policies
In general, the MediaWiki JavaScript coding conventions shall apply to the Wikibase extension as well. A few differences and additional specifications are outlined below.

Function and variable prefixes
Since JavaScript does not support encapsulation, we are using an underscore to mark functions and variables private discouraging the use out of their scope:

jQuery wrapped elements should be prefixed with a dollar sign to be able to distinguish those easily from other variables. In addition, this allows naming a jQuery node like the instance of a widget that is initialized on that node:

Whitespace
In contrast to the MediaWiki coding conventions, we discourage using a space character after keywords followed by a left paranthesis to indicate that the content of the parantheses directly refers to the keyword:

Indentation
When chaining more than one function call, each call should be placed in a new line without applying any indentation to prevent ending up with deep indentation levels:

This convention does not apply when assigning a variable. However, one should not declare other variables along with such a variable declaration. Just separate the variable declarations:

Line breaks
Like to the MediaWiki coding conventions, lines should not exceed the length of 100 characters (tab equals 4 spaces). When a line break within a statement cannot be avoided, the operator should be wrapped to the next line indented by an extra level to indicate the continuation of the statement. Closing parentheses should always be on the same level like their corresponding opening ones.

Keeping context in callbacks: jQuery.proxy; vs. var self = this;
For consistency throughout the codebase, usage of is preferred over

jQuery.Promise
When dealing with promises, the,   and   methods should be used rather than the less expressive. Callback parameters given when the promise gets resolved should be documented explicitly.

Accessing jQuery widget instances
For accessing jQuery widget instances, the .data function should be used resulting in a more expressive code:

jQuery Widget documentation
Since there should be not more than one widget per file, the file level documentation should be used to document a widget. In addition to the default documentation tags @since, @licence and @author, the documentation header should contain a description of the widget and documentation of the widget's options as well as the events triggered by the widget using the @option and @event tag respectively. Since the @since tag references a particular version of the component the widget resides in, there is no use in applying it to widgets independent from the component (eventually, such a widget should be moved out of the component).

Optional arguments
In function documentations, optional function arguments should be documented with square brackets around the variable name making their optional nature more obvious.

Instead of...

... use:

Mixed arguments
Can be documented as