Dev Wiki:Coding conventions

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

Coding conventions
Community policy & guides
Project & request pages

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

• Wrap the whole module in <nowiki></nowiki> or <pre></pre> tags to prevent code like [[...]] or {{...}} from being interpreted as wikitext:

-- BAD - adds the module to Special:WhatLinksHere/Not_a_real_page
local redlink = "[[Not a real page]]"

-- GOOD - sometimes a string is just a string
-- <nowiki>
local redlink = "[[Not a real page]]"
-- </nowiki>

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

• JavaScript: {{Infobox JavaScript}} and {{Script Install}}.
• CSS: {{Infobox CSS}} and {{CSS Install}}.
• Lua: {{Infobox Lua}} and {{Lua Install}}
• Application: {{Infobox Application}}
• Wikitext: {{Documentation}}

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.