Wiktionary:Coding conventions

From Wiktionary, the free dictionary
Archived revision by AIVOP (talk | contribs) as of 12:20, 20 April 2022.
Jump to navigation Jump to search

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: IPAchar, Latinx, musical, polytonic, Ruminumerals.)

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 a 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 that 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 {{categorize}}, {{catlangname}} and {{catlangcode}} 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 that 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

  • The main table, containing functions available to templates and other modules shall be named export, and declared as a local variable at the top of the module.
  • Exported functions to be exclusively invoked from templates shall accept only one argument, named frame.
  • 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 holding return values from require() (i.e. imported modules) should have their names prefixed with m_.
  • Words in variable and function names should be separated with underscores. Variables should be all-lowercase unless other reasons dictate otherwise.
  • Comments should be used sparingly; good code does not need much commenting. Keep comments brief and to the point. Do not put ASCII art in the comments.
    • Comments should not be used for documentation; use the documentation subpage instead.
  • Unit tests for a module, if any, shall 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 shall have its method whose name starts with check_.
    • An alternative test framework, Module: ScribuntoUnit, has been imported from Wikipedia and can also be used.
  • When feasible, functions should be written to be callable both from templates and directly from other Lua functions, without creating a frame (or a table imitating one). To accomplish that, check at the very beginning of the function if its first argument is a table, using type() (or check if it equals mw.getCurrentFrame()).
    • Alternatively, you may designate a separate function or module for functions callable from templates. By convention, this is done by creating a submodule named /templates.
  • Conversely, when a native Lua function is available for a particular task, use it directly instead of calling a template. frame:expandTemplate should be used sparingly.
  • Don't forget to monitor Category: Pages with module errors after making substantial edits.

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

Verb inflection

Grammatical cases

And above all

VI. Break any of these rules sooner than say anything outright barbarous.