Wiktionary:Coding conventions
Appearance
| This is a Wiktionary policy, guideline or common practices page. Specifically it is a policy think tank, working to develop a formal policy. | |
| Policies – Entries: CFI - EL - NORM - NPOV - QUOTE - REDIR - DELETE. Languages: LT - AXX. Others: BLOCK - BOTS - VOTES. |
Codes
- Language, family and script codes are based on BCP 47.
- Non-standard language and family codes should consist of a (preferably standard) parent family code and a Wiktionary-specific suffix.
- Codes for protolanguages should consist of a family code and a
-prosuffix. - Non-standard script codes should consist of a language code prefix, and a standard ISO 15924 script code. (Exceptions:
Ipach,Music,Polyt,Rumin.)
Templates
- Names of templates related to a particular language should be prefixed by the language code, see WT:List of languages. Likewise for templates specific to a script; see WT:List of scripts for a list of script codes.
- For proto-languages, it is permitted to drop
-profrom the code, and use the code of the family alone.
- For proto-languages, it is permitted to drop
- Names of reference templates should have the prefix “
R:”. If the reference is for one specific language, it is often followed by language code and a colon. - Likewise, usage note templates should have the prefix “
U:”. - Relatively complex templates, especially those with parser functions (like
{{#if:}}or{{#switch:}}), should have the code split up onto multiple lines for readability. Wikicode constructs should be aligned so that the starting curly braces and ending curly braces line up vertically. The line breaks themselves should be wrapped in comments; each line should end with a begin-comment tag<!--paired with an end-comment tag-->on the next line. This avoids line breaks accidentally appearing in the output or parameters of templates. Like so:
<!--
-->{{#if:{{{something|}}}<!--
-->|<!--
-->do things<!--
-->}}<!--
-->
- Templates which add categories that are only intended for entries should have extra code that only adds the category in the entry namespaces (main namespace and Appendix:). The templates
{{cat}}(for raw categories),{{cln}}(for categories beginning with a language name, aka grammar categories) and{{C}}(for categories beginning with a language code, aka topic categories) do this automatically, so using them is preferred. - If a template adds a category, but it would be desirable to suppress that category in some cases, it should have a
|nocat=parameter which prevents that. - If you want to accept a variable number of named parameters of the same type in a template, the first shall be named
|foo=, while the rest shall be|foo2=,|foo3=,|foo4=and so on. - When naming template parameters (or their values), try referring to #Customary abbreviations instead of inventing your own; likewise, use appropriate codes to refer to languages, scripts and families.
- Headword-line templates should either be implemented in a separate module using Module:headword, or use
{{head}}. - Redirects for templates intended for entries should be created sparingly.
- Avoid doing string processing in templates. If you find yourself in need of a “substring” function, you might have crossed the point where the template should be converted to Lua.
Lua
Writing modules
- Modules should be named beginning with a lowercase letter. Use spaces between multiple words (e.g. Module:headword utilities).
- The main table, containing functions available to templates and other modules, should be named
exportand declared as a local variable at the top of the module. - Exported functions meant to be invoked from templates should accept only one argument, named
frame. - Functions meant to be invoked from templates should use Module:parameters to validate the template arguments of the function (those retrieved using
frame:getParent().args). By convention, the validated template arguments are stored in a local variable namedargs. If the function takes invocation arguments (i.e. arguments passed directly in the#invoke:parser function and retrieved usingframe.args), they should also be validated using Module:parameters and should be stored in a local variable namediargs. - It is not recommended to create a single function written to be callable both from templates and directly from other Lua functions. Instead, there should be separate functions or modules for functions callable from templates. By convention, if the template-callable functions are placed in a separate module, the module is named ending with
/templates. - Do not import modules directly from Wikipedia. Wikipedia uses very different conventions from Wiktionary, and most library modules provided by Wikipedia already exist in Wiktionary in a different form but providing equivalent or superior functionality.
- Don't forget to monitor Category:Pages with module errors after making substantial edits.
Coding style
- Code should be indented with tabs.
- Variables should be explicitly declared
local. No exported functions should be declared with thelocal functionconstruct. Global variables should not be used. - Variables, functions and methods should use snake case (
my_awesome_function) not camel case (myAwesomeFunctionorMyAwesomeFunction). A few existing modules (e.g. Module:languages, Module:table) do use camel case, but no new modules should be created that use camel case. - Strings should be delimited with double quotes, not single quotes, unless the string itself contains a double quote in it.
- Functions that take a single string as a value should use parentheses around the string, i.e. use the syntax
require("Module:table"), notrequire "Module:table". However, if a function takes a single table as a value, it is okay to omit the parentheses.
Invoking modules
- Beware that some data modules (e.g. Module:links/data) should be loaded with
mw.loadData()rather thanrequire(), which ensures they get loaded only once per page instead of once per template invocation. - When a native Lua function is available for a particular task, use it directly instead of calling a template.
frame:expandTemplateandframe:preprocessshould be used sparingly. - Variables holding return values from
require()(i.e. imported modules) should have their names prefixed withm_.
Unit tests
- Unit tests for a module, if any, should be put on a
/testcasessubpage.- Unit test modules should use Module:UnitTests. See that module’s page for usage details.
- If a specific kind of test is to be performed repeatedly, it should have its own method whose name starts with
check_. - There is an alternative test framework, Module:ScribuntoUnit, imported from Wikipedia, but its use is not recommended.
JavaScript
- Scripts should start with a prologue containing
// {{documentation}} <nowiki>, preferably preceded by a strict mode declaration. - Enabling at least the following JSHint options is recommended:
/*jshint strict:true, undef:true, latedef:true */ /*global mw, jQuery */- Preferably, strict mode should be enabled, globally or per-function. This makes the
strictJSHint option implicit. - Enabling the following options is permitted:
boss,loopfunc,debug,sub,scripturl,validthis,unused. - Warnings raised by JSHint should be addressed either by code refactoring or enabling an option listed above.
- Preferably, strict mode should be enabled, globally or per-function. This makes the
- Identifiers should use Java camelCase.
- Code should be indented with tabs. Placement of curly brackets should follow Crockford style, based on K&R: always on the same line as the control structure. Omitting a bracket pair not required by syntax is permissible.
- Not increasing an indentation level is permissible in cases where mere boilerplate (e.g. a wrapper callback function, or a condition placed over the entirety of code) is what would normally warrant increasing indentation.
Customary abbreviations
a– aspectadj– adjectiveadv– adverbalt– alternative display (link label)c– common genderconj– conjugation or conjunctiondordu– dualdecl– declensionf– feminineg– genderglossort– translation gloss (for non-English terms)id– sense ID (see{{senseid}})impf– imperfectiveinfl– inflectionlang– language codem– masculine (exception:{{m}}= mention)n– neuterporpl– pluralpf– perfectivepos– part of speechpron– pronoun or pronunciationpronunc– pronunciationrf...– request for...sorsg– singularsc– script codetr,translit– transliteration