Jump to content

Wiktionary:Coding conventions

From Wiktionary, the free dictionary

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 -pro suffix.
    • 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 -pro from the code, and use the code of the family alone.
  • 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 export and 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 named args. If the function takes invocation arguments (i.e. arguments passed directly in the #invoke: parser function and retrieved using frame.args), they should also be validated using Module:parameters and should be stored in a local variable named iargs.
  • 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 the local function construct. Global variables should not be used.
  • Variables, functions and methods should use snake case (my_awesome_function) not camel case (myAwesomeFunction or MyAwesomeFunction). 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"), not require "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 than require(), 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:expandTemplate and frame:preprocess should be used sparingly.
  • Variables holding return values from require() (i.e. imported modules) should have their names prefixed with m_.

Unit tests

  • Unit tests for a module, if any, should be put on a /testcases subpage.
    • 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 strict JSHint 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.
  • 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 – aspect
  • adj – adjective
  • adv – adverb
  • alt – alternative display (link label)
  • c – common gender
  • conj – conjugation or conjunction
  • d or du – dual
  • decl – declension
  • f – feminine
  • g – gender
  • gloss or t – translation gloss (for non-English terms)
  • id – sense ID (see {{senseid}})
  • impf – imperfective
  • infl – inflection
  • lang – language code
  • m – masculine (exception: {{m}} = mention)
  • n – neuter
  • p or pl – plural
  • pf – perfective
  • pos – part of speech
  • pron – pronoun or pronunciation
  • pronunc – pronunciation
  • rf... – request for...
  • s or sg – singular
  • sc – script code
  • tr, translit – transliteration

Ignore all rules