Coding Conventions(JavaScript,CSS,Lua)

**Tips Before Reading:This article is written in English,self-translation may lead to deviations in the meaning of the text.**

**提示:** **阅读提示：本文用英语书写，自行翻译可能导致文意偏差。**

This page is a style guide for Heaven Detective Agency 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:

**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 (
 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.

* **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

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

```
<noinclude>{{LangSelect}}</noinclude><includeonly>{{Languages}}
{{Infobox JavaScript
}}
{{{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}}
}}

```

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