Manual:Coding conventions

From MediaWiki.org

This page describes the coding conventions used within the MediaWiki codebase, including appropriate naming conventions. It is meant to be descriptive, not dictatorial. If you do choose to follow these guidelines, it will probably be easier for you to collaborate with others on the project, but if you want to contribute in your own style by all means do so (though don't be surprised if your code gets reformatted at a later date).

[edit] Indentation and spacing

• Code is indented with tabs, not spaces.
• We use K&R style brace matching. Braces are added the end of lines for function declarations, not on a new line.
• In general, one space is used on the inside of each non-empty parenthesis in function definitions and calls:

function wfBlah( $a, $b ) {
    // ...
}

Also:

array( 1, 2, 3 )

rather than:

array(1,2,3)

In emacs (see also php-mode), you can approximate this style with a custom minor mode in your .emacs file, i.e.

(defconst mw-style 
      '((c-offsets-alist . (
                            (case-label . +)
                            (arglist-close . 0)
                            ))))
 
 
(c-add-style "MediaWiki" mw-style)
 
(define-minor-mode mw-mode
  "tweak style for mediawiki"
  nil " MW" nil
  (if mw-mode
      (progn
        (setq tab-width 4 c-basic-offset 4)
        (c-set-style "MediaWiki"))
    (kill-local-variable 'tab-width)
    (kill-local-variable 'c-basic-offset)))

[edit] Classes

• As a holdover from PHP 4.x's lack of private class members and methods, older code will be marked with comments such as /** @private */ to indicate the intention; please respect this as if it were enforced by the compiler

  Newer code will use proper visibilities, but do not add it to existing code without first checking, testing and refactoring as required, because the above rule has been broken in several places

• In general, member variables are named mXxx to distinguish them, which helps spot missing instances of $this, which will cause odd breakage due to PHP's silent initialisation of the variable
• We prefix the names of global variables with wg (wiki global) in order to make it easier to distinguish them, which thus makes it easier to spot missing global declarations

[edit] Naming conventions

There is a preference for lowerCamelCase when naming functions or variables. For example:

private function doSomething( $userPrefs, $editSummary ) {

There are also some prefixes used in different places:

[edit] Functions

• wf (wiki functions) - Top-level functions, e.g. function wfFuncname() { ... }

[edit] Variables

• wg - global variables, e.g. $wgVersion, $wgTitle
• m - object member variables: $this->mPage
  • This is not universally observed, but try to stay consistent within a class.

[edit] Extension Functions and Variables

• ef - extension functions : top-level functions added by user extensions
• eg - extension globals

[edit] HTTP and session stuff

• ws - Session variables, e.g. $_SESSION['wsSessionName']
• wc - Cookie variables, e.g. $_COOKIE['wcCookieName']
• wp - Post variables (submitted via form fields), e.g. $wgRequest->getText('wpLoginName')

[edit] Database

• Table names are usually singular nouns: user, page, revision, etc
  • Except when they're not: pagelinks, categorylinks...
• Column names are given a prefix derived from the table name: the name itself if it's short, or an abbreviation:
  • page -> page_id, page_namespace, page_title...
  • categorylinks -> cl_from, cl_namespace...

[edit] Common local variables

It is common to work with an instance of the Database class; we have a naming convention for these which helps keep track of the nature of the server to which we are connected. This is of particular importance in replicated environments, such as Wikimedia and other large wikis.

• $dbw - a Database object for writing (a master connection)
• $dbr - a Database object for non-concurrency-sensitive reading (may be a read-only slave, slightly behind master state)

[edit] Inline documentation

• The PHPDoc or Doxygen documentation style is used (both styles are very similar for the subset that we use). For example: giving a description of a function or method, the parameters it takes (using @param), and what the function returns (using @return), or the @package, @subpackage or @author tags. Please use "@" rather than "\" as the escape character if using Doxygen (e.g. use @param rather than \param) - both styles work in Doxygen, but the @param style works with PHPDoc too, whereas the \param style does not.

• General format for parameters is such: @param type [$varname] description so make sure you don't put [$varname] before type.

[edit] Messages

• When creating a new message, use hyphens (-) where possible. So for example, "some-new-message" is a good name, while "someNewMessage" and "some_new_message" are not.
• If the message is going to be used as a label which can have a colon (:) after it, don't hardcode the colon; instead, put the colon inside the message text. Some languages (such as French) need to handle colons in a different way, which is impossible if the colon is hardcoded.
• HTML class and ID names should be prefixed with "mw-". It seems most common to hyphenate them after that, like "mw-some-new-class" instead of "mw-somenewclass" or "mw-some_new_class", but there doesn't appear to be a clear convention at present.

Languages:

English  • 日本語