Wikipedia:Debugging templates
 | This is an essay. It contains the advice or opinions of one or more Wikipedia contributors. This page is not an encyclopedia article, nor is it one of Wikipedia's policies or guidelines, as it has not been thoroughly vetted by the community. Some essays represent widespread norms; others only represent minority viewpoints. |
This essay describes techniques to debug a Wikipedia template for various problems in the structure of the wikitext used. The wikitext parser has been used for years and, although the markup might seem confusing, the language is extremely reliable: the nesting of if-else functions, nested up to 40 levels deep, can be trusted to correctly match the corresponding 40 if-else clauses and pass hundreds of parameters under the correct names, even in a 2,000-line template. However, there are some restrictions which might surprise some users, such as passing an equals-sign "=" in data by template "{{=}}" (see below: "Unusual restrictions").
Common problems
[edit]The following list shows some common problems.
- E1. Display: {{#if: means: An if-function with no closing "}}"
- E2. Display: {{#switch: means: A switch-function with no closing "}}"
- E3. Display: {{ 1. switch: means: Unclosed switch-function split from "{{" on prior line
- E4. Display: --> means: Unopened HTML-style comment
- E5. Display: }} means: Extra closing "}}"
- E6. Display: }} }} means: Possible unopened template "mytemplate|x}}"
During edit-preview, a template acts as if in "debug-mode" and will display any text or the result of a calculation or logic branch.
- Double-check for unclosed comments: <!--xxx-> is unclosed, needing "-->"
- Put debug-print text outside braces: {{__}}HERE{{___}}
By inserting debug-print text (such as "HERE1" or "HERE2"), then the flow of the logic can be deduced between the printed text portions.
Unusual restrictions
[edit]There are some restrictions which often surprise (or re-surprise) users. Perhaps the most-common problem is passing an equals-sign in data.
- To pass "=" data: put parameter number "1=a=b" or encase in a null parameter: {{{|a=b}}}.
A common mistake is to try to {nowrap} a line containing an "=" and nothing is displayed:
- {{nowrap |y = x + 3}} Result: (nothing)
- {{nowrap |1=y = x + 3}} Result: y = x + 3
- {{color |darkorange| Error: x=0}} Result: darkorange(nothing)
- {{color |darkorange| 2=Error: x=0}} Result: Error: x=0
- {{color |darkorange| {{{|Error: x=0}}} }} Result: Error: x=0
A related problem is to show a vertical bar pipe "|" inside template parameters, by using "|" or the bang template: {{!}}. Other &# codes can be found at the page wp:CODES, as a table of common character codes.
There are many, many tricks to debugging, and most template problems can be pinpointed within a few minutes, by using a combination of debugging techniques, such as inserting debug-print text and re-proofreading to double-check for unclosed if-functions or unclosed comments, in areas recently changed. A scan for unclosed comments "<!-- -->" could be done with a simple HTML tool as a syntax checker, because they are HTML-style comments, unless the "}}" tokens confuse the issue.
Make small changes and test
[edit]In general, it is best to make only a few changes to a template, at a time, to first test the results, and then re-examine the (few) areas which were changed to look for common mistakes. For example, if planning to change 5 areas in a template, just change one spot first and test the results, then when sure, repeat or expand the change in other areas.
By comparison, changing 20 spots and running a test might take 100x times longer to pinpoint a simple new error, while trying to second-guess which among the 20 areas had introduced the new bug. In typical cases of bug corrections, 1-in-10 changes will introduce yet another bug. So 20 changes would predict 2 new problems (at least).
Keep old revisions as lifeboats
[edit]As a safety net (or lifeboat), programmers often save several prior versions of a template, such as in numbered computer text files, and then in the event of a complex new mess, save the current version somewhere else, then just return to a prior, tested version and re-introduce some changes more carefully. In many cases, the worst bug can be spotted quickly against the prior revision, allowing to restore the entire saved current version to re-apply the bugfix and continue onward, without actually reworking all changes into the prior old revision (as a temporary voyage in the old "lifeboat").
Beware sleeper bugs in rare cases
[edit]Although most bugs are caused by recent changes, there can be "sleeper bugs" left over from weeks/months ago, such as an unclosed comment which gobbled a section of code rarely used, until recent edits triggered that section of the markup.