Fandom Developers Wiki
Register
Advertisement

This administration team will split this page into more detailed, language-specific guides.

For code review, see Board:JS Development, Board:CSS Development or Board:Scribunto Help.
For requesting a new script , see Board:Script Suggestions.

This page is a style guide for Fandom Developers Wiki code & documentation. It's a set of standards and best practices created to help developers write better code.

It encourages consistency between items, which makes them easier to read, test, and maintain. That said, you should always use your best judgement when coding, and avoid the cargo cult.

Naming conventions[]

The following table lists expected page titles for Dev Wiki items:

Item Location
Script/style/application documentation PAGENAME
Lua documentation Global Lua Modules/PAGENAME
JavaScript module MediaWiki:PAGENAME.js
JavaScript submodule MediaWiki:PAGENAME/<submodule>.js
CSS stylesheet MediaWiki:<PAGENAME>.css
CSS component for JS script MediaWiki:PAGENAME/<component>.css
Lua module Module:PAGENAME
Lua submodule Module:PAGENAME/<submodule>
Lua test cases Module:PAGENAME/testcases
A stylesheet related to a Lua module MediaWiki:Global Lua Modules/<PAGENAME>.css
MediaWiki/HTML dependency Template:PAGENAME

Note: Historically, Dev Wiki scripts and stylesheets didn't obey these conventions. They were named PAGENAME/code.<ext> and were stored as subpages of the documentation page. However, due to security concerns, these were moved to the MediaWiki namespace, which makes /code.<ext> unnecessary for new scripts.

Coding conventions[]

JavaScript[]

  • When developing a script, wrap code in any IIFE like so:
(function (window, $, mw) {
    // code
}(this, jQuery, mediaWiki));
  • When using >3 MediaWiki variables, you can cache them using mw.config.get:
var conf = mw.config.get([
    'wgAction',
    'wgContentLanguage',
    'wgUserLanguage',
    'wgVersion'
]);
console.log(conf.wgContentLanguage);
  • Scope window variables for libraries to window.dev:
(window.dev = window.dev || {}).script = {};
  • Prevent double loading and add other load protections if necessary, usually in the below format:
if (
    window.PAGENAMELoaded ||
    otherLoadProtection
) {
    return;
}
window.PAGENAMELoaded = true;
  • If the script already exposes a global variable or adds a class, it might be preferable to check for that variable or class during double-load prevention instead of creating a new global.
  • If the script uses a significant amount of CSS, either through inline CSS or mw.util.addCSS, it should generally import a .css page containing the styling via an importArticle statement.

CSS[]

  • In stylesheets, please don't use HTML tag names as selectors - this causes style leakage:
/* BAD - affects *14* elements in this page */
.skin-oasis section {
    border-width: 1px;
}
/* GOOD - is scoped to a specific element */
.skin-oasis .activity-module {
    border-width: 1px;
}
  • Limit your CSS in scope with >=3 selectors - this reduces bugs:
/* BAD - affects multiple scripts */
.wds-global-navigation__user-menu .wds-list {
    font-weight: bold;
}
/* GOOD - targets the user menu list only */
.wds-global-navigation__user-menu > .wds-dropdown > .wds-list {
    font-weight: bold;
}

Lua[]

  • Create the exported package table at the start of the module, not the end:
-- BAD - module creates table at the end
function hello(frame)
    return 'Hello World!'
end
return {
    hello = hello
}
-- GOOD - module creates table at the start
local p = {}
function p.hello(frame)
    return 'Hello World!'
end
return p
  • Datastores should encapsulate the table in a return { --[[--]] } statement.

Documentation best practice[]

A script's documentation likely includes a number of things. The most common are:

  • A description of the script and its features
  • Import instructions and any setup instructions
  • Details about configuration, interface changes and commands

Much of the information you might want to include is in ready-to-use templates. Information and attribution is added using a infobox template. JavaScript, CSS, and Lua documentation should use an installation template.

Documentation i18n[]

For translation guidance, see Project:I18n#Translation.

To facilitate i18n in your script documentation, you can structure the main documentation page like so:

<noinclude>{{LangSelect}}</noinclude><includeonly>{{Languages}}
{{Infobox JavaScript
| Author =
| Description = {{{description|Description of your script.}}}
| Code = [[MediaWiki:{{BASEPAGENAME}}.js]]
| Updated = {{Updated|MediaWiki:{{BASEPAGENAME}}.js}}
| Scope =
| Type =
}}
{{{intro|'''{{subst:BASEPAGENAME}}''' is a ...}}}

== {{#invoke:I18n|getMsg|Documentation|installation}} ==
{{Script Install}}
</includeonly>

The main page contains the English translation, and is displayed to users using {{LangSelect}}.

Then, create language-specific subpages in the following format:

{{:{{subst:BASEPAGENAME}}
| description  = Description of your script.
| intro        = '''{{subst:BASEPAGENAME}}''' is a ...
}}

You can also use the documentation translation wizard to automatically create the transclusion for a translation.

Advertisement