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. |
Various editors like to tweak the wikicode in various ways while editing, and a handful even go around doing little but making such changes. Some of these edits are helpful, many are not, a few are apt to lead to editorial conflict, and most all of them are purely cosmetic (serve no reader-facing purpose or internal maintenance need), so should not be done without making at least one substantive improvement to the article in the same edit, when they should be done at all.
There is no " Wikipedia:Coding standards" page and surely never will be; we've gotten on for over two decades without a policy on this. However, many particular aspects of wikicoding style are covered by various policies and guidelines and other internal documentation (in a rather scattered manner), and most of the rest are covered by clearly observable editorial consensuses. When 95% of cases are done a certain way, this is a community-accepted best practice. When it's virtually impossible to find something done a particular way except in edits by brand new users who don't know our practices, or in very old material that has not been cleaned up to reflect current practices, then there is clearly an editorial consensus against doing it that way. If usage is split about 50/50, then there is clearly a consensus that it's a matter left to editorial discretion on an article-by-article basis.
Consensus still exists whether or not a rule has been written that records that consensus. One of the ones that is written is that edit-warring over a style (including code style) quibble is disruptive, as is going around changing, for no objective reason, a perfectly acceptable style to one you just subjectively like better. Pointless minor twiddles clog up watchlists, make checking recent changes at a page for things of substance that need to be examined much more difficult, and encourage petty "stylewarring" over trivia.
All of the following are generally constructive, though as with other trivial tweaking most of these should only be done as part of a more substantive improvement (those that are themselves substantive and can be done as their own edit are noted below). They range from following specific guidelines, through complying with technical or accessibility needs, to simply being overwhelmingly dominant usability best practices:
*
, #
, or ;
and :
line-beginning markup,
MediaWiki generates HTML lists of the appropriate sort, but terminates the list and starts a new one if there is an empty line between list items. This problem does not affect lists created manually with the underlying
HTML elements for lists. Fixing list gaps is a substantive change.{{DEFAULTSORT:}}
if any), below any
navbox or other content. Categories should always be the last thing on the page.{{
Short description}}
to be above any other templates and page content. The short description should always be the very first thing on the page, even above warning/cleanup tags, protection templates, disambiguation hatnotes, etc.{{
Short description}}
,
hatnotes, dialect and date format notices, cleanup/warning templates, and an infobox. No blank line is needed between any of these and the lead sentence of the content, either.{{cite book |last=Smith |first=Jane B. |title=Breeding Weasels |date=2023 |...}}
, instead of the run-together mess {{cite book|last=Smith|first=Jane B.|title=Breeding Weasels|date=2023|...}}
or the space-consuming {{cite book | last = Smith | first = Jane B. | title = Breeding Weasels | date = 2023 | ... }}
. The one-space-between-parameters form recommended here is that used in the vast majority of our citations, so clearly has consensus as a best practice, and it is enforced by
VisualEditor anyway.
{{cite book| last=Smith| first=Jane B.| title=Breeding Weasels| date=2023| ...}}
, which adheres the parameter-opening |
to the data of the previous parameter.<
ref>
tags to have quoted parameters, to have a space before />
, and to remove unneeded spacing: change <ref name = Foo group = note/>
to <ref name="Foo" group="note" />
<ref name=Tachibana-2017>
or <ref name=Krajčovič1975>
or even <ref name=Smith Jones 2023>
. Because any editor at any time might rename ref tags, it is always safest to include the quotation marks, no matter what the present ref names are. It is also a format that is enforced by
VisualEditor anyway. />
is understood by more parsers than the version without, so this is better for
reuse of Wikipedia content.<br>
and <br/>
with <br />
for the same reason as above, and because the one with no slash at all isn't even understood by
our own syntax highlighter. (Same goes for the infrequent <hr>
and <hr/>
replaced with <hr />
, though the wikicode ----
also works as long as it's at the start of its own line.)[[ Cat | domestic cat ]]
into [[Cat|domestic cat]]
a [[Dog|dog]] and two [[Cat|cats]]
into a [[dog]] and two [[cat]]s
.[[José González|Jose Gonazales]]
should be [[José González]]
, unless there is a very good reason for the piping, e.g. because the usage is in a direct quotation. This is a substantive change.<i>...</i>
with ''...''
, etc.<blockquote>...</blockquote>
to {{
blockquote|...}}
). The templates have additional parameters that provide features, often have custom
CSS styling for a consistent appearance, and often CSS classes for treatment in custom
user stylesheets.''...''
or '''...'''
with
Semantic HTML templates {{
em|...}}
or {{
strong|...}}
respectively (these use the underlying <em>
and <strong>
elements). This should not be done when the markup is simply conventionalized, non-emphasis, visual formatting, like italics for
titles of works or boldface for
pseudo-headings. Switching to semantic markup is a substantive change.{{
Use DMY dates}}
or {{
Use MDY dates}}
at the top of the article; or if there isn't one, the DMY or MDY date format that already dominates in the article (not YYYY-MM-DD format); or if it's a completely random mess, to whichever makes the most sense for that article (e.g. American MDY format if the subject has
strong ties to the US, but probably DMY format otherwise). If in doubt, open a discussion on the talk page about what date format to use. Date cleanup is a substantive change.
|access-date=
and |archive-date=
.]...
instead of the precomposed …
Unicode character", and "in measurements, put a space between the numerical measure and its unit symbol", that have something to do with how things are in the wikicode, but this list is not going to enumerate them all, as they are really about content not code per se (and doing so would essentially be duplicating the MoS, in a page that is meant to be a quick reference).<
syntaxhighlight lang="wikitext">...</syntaxhighlight>
(changing the lang
value to whatever is needed for the code type in question). This is a substantive change.
[1]==Heading==
level-2 markup, and subheadings proceed in order, level-3 ===Sub-heading===
through (at least in theory) level-6 ======Sub-sub-sub-sub-heading======
, without intervening levels skipped. (An article actually using all 6 heading levels probably needs to be restructured better.)
=Title=
, are not used in articles. A =Title=
corresponds to <h1>Title</h1>
and is reserved for the auto-generated article title. Some non-articles use =Heading=
anyway, usually maintenance pages that are transcluding multiple entire other pages, and usually should be left alone in this regard. But in an article, a =Heading=
error should be converted to ==Heading==
, with adjustment to any sub-headings that are topically under it, as needed.==Heading==
followed directly by ====Sub-sub-heading====
, convert the latter to ===Sub-heading===
, and adjust any further-nested heading levels under that, as needed.[[Wikipedia:Biographies of living persons#Subjects notable only for one event|one event]]
not [[WP:BLP1E|one event]]
; use {{
crossref|pw=y|See also {{
section link|Wikipedia:Manual of Style#Dashes}}}}
, not {{
crossref|pw=y|See also [[MOS:DASH]]}}
.
The following are generally not constructive, and range from pointless wastes of time, through annoying or controversial, to disruptive and problematic:
== Heading ==
to ==Heading==
or vice versa, other than to simply make them
consistent within the same article. Neither format is preferred by consensus.* List item
to *List item
or vice versa, other than to simply make them consistent within the same article. Neither format is preferred by consensus.[[Cat|domestic cat]]
piped links into lower-case [[cat|domestic cat]]
. This serves no purpose of any kind and actually makes it harder to notice a piped link when visually scanning the code.{{Template name|...}}
to {{template name|...}}
or vice versa. This serves no purpose of any kind.{{citation needed|...}}
with a shortcut like {{
fact|...}}
or {{
cn|...}}
. Over the years, Wikipedia has consistently been renaming all templates (at least those with any usage in mainspace) to be at descriptive, sensible names for the benefit all editors, especially new ones. Using shortcut versions makes it more difficult to know what issue is being flagged. And we have a bot that goes around replacing the shortcuts for this sort of template with the real template name anyway, so doing it is futile. (But no one cares all that much if you insist on using the shortcut version to begin with. Just expect it to be replaced.)
{{
harvp}}
has a much longer real name ({{
Harvard citation year brackets}}
) and having this appear numerous times throughout the article would not be helpful to anyone. Similarly, the {{
"'"}}
shortcut shows exactly what that template does, but it cannot actually have that as the page name for technical reasons; its long name {{
Double+single+double}}
isn't useful in the article's wikitext.[[Franklin Roosevelt]]
to [[Franklin D. Roosevelt]]
or [[Franklin D. Roosevelt|Franklin Roosevelt]]
just to "fix a redirect". However, it is perfectly acceptable to change it to [[Franklin D. Roosevelt]]
if for some reason it is preferred that "Franklin D. Roosevelt" actually appear in the visible text. Editors should also not change
redirects with possibilities like [[Journal of the Franklin Institute]]
to [[Franklin Institute#Journal of the Franklin Institute|Journal of the Franklin Institute]]
, so that readers arrive at the more pertinent article in the eventuality that it is created."
[[Kesha]]
to her sometimes-used marketing sylization via [[Kesha|Ke$ha]]
or [[Ke$ha]]
just because you think it looks cool; changing [[Sony]]
to [[SONY]]
or [[Sony|SONY]]
to mimic their logo; etc.<
syntaxhighlight>
, see
mw:Extension:SyntaxHighlight, and in particular its link to the list of supported languages of the underlying Pygments syntax-highlighting library at
https://pygments.org/languages/ (see the "Short name(s)" column).
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. |
Various editors like to tweak the wikicode in various ways while editing, and a handful even go around doing little but making such changes. Some of these edits are helpful, many are not, a few are apt to lead to editorial conflict, and most all of them are purely cosmetic (serve no reader-facing purpose or internal maintenance need), so should not be done without making at least one substantive improvement to the article in the same edit, when they should be done at all.
There is no " Wikipedia:Coding standards" page and surely never will be; we've gotten on for over two decades without a policy on this. However, many particular aspects of wikicoding style are covered by various policies and guidelines and other internal documentation (in a rather scattered manner), and most of the rest are covered by clearly observable editorial consensuses. When 95% of cases are done a certain way, this is a community-accepted best practice. When it's virtually impossible to find something done a particular way except in edits by brand new users who don't know our practices, or in very old material that has not been cleaned up to reflect current practices, then there is clearly an editorial consensus against doing it that way. If usage is split about 50/50, then there is clearly a consensus that it's a matter left to editorial discretion on an article-by-article basis.
Consensus still exists whether or not a rule has been written that records that consensus. One of the ones that is written is that edit-warring over a style (including code style) quibble is disruptive, as is going around changing, for no objective reason, a perfectly acceptable style to one you just subjectively like better. Pointless minor twiddles clog up watchlists, make checking recent changes at a page for things of substance that need to be examined much more difficult, and encourage petty "stylewarring" over trivia.
All of the following are generally constructive, though as with other trivial tweaking most of these should only be done as part of a more substantive improvement (those that are themselves substantive and can be done as their own edit are noted below). They range from following specific guidelines, through complying with technical or accessibility needs, to simply being overwhelmingly dominant usability best practices:
*
, #
, or ;
and :
line-beginning markup,
MediaWiki generates HTML lists of the appropriate sort, but terminates the list and starts a new one if there is an empty line between list items. This problem does not affect lists created manually with the underlying
HTML elements for lists. Fixing list gaps is a substantive change.{{DEFAULTSORT:}}
if any), below any
navbox or other content. Categories should always be the last thing on the page.{{
Short description}}
to be above any other templates and page content. The short description should always be the very first thing on the page, even above warning/cleanup tags, protection templates, disambiguation hatnotes, etc.{{
Short description}}
,
hatnotes, dialect and date format notices, cleanup/warning templates, and an infobox. No blank line is needed between any of these and the lead sentence of the content, either.{{cite book |last=Smith |first=Jane B. |title=Breeding Weasels |date=2023 |...}}
, instead of the run-together mess {{cite book|last=Smith|first=Jane B.|title=Breeding Weasels|date=2023|...}}
or the space-consuming {{cite book | last = Smith | first = Jane B. | title = Breeding Weasels | date = 2023 | ... }}
. The one-space-between-parameters form recommended here is that used in the vast majority of our citations, so clearly has consensus as a best practice, and it is enforced by
VisualEditor anyway.
{{cite book| last=Smith| first=Jane B.| title=Breeding Weasels| date=2023| ...}}
, which adheres the parameter-opening |
to the data of the previous parameter.<
ref>
tags to have quoted parameters, to have a space before />
, and to remove unneeded spacing: change <ref name = Foo group = note/>
to <ref name="Foo" group="note" />
<ref name=Tachibana-2017>
or <ref name=Krajčovič1975>
or even <ref name=Smith Jones 2023>
. Because any editor at any time might rename ref tags, it is always safest to include the quotation marks, no matter what the present ref names are. It is also a format that is enforced by
VisualEditor anyway. />
is understood by more parsers than the version without, so this is better for
reuse of Wikipedia content.<br>
and <br/>
with <br />
for the same reason as above, and because the one with no slash at all isn't even understood by
our own syntax highlighter. (Same goes for the infrequent <hr>
and <hr/>
replaced with <hr />
, though the wikicode ----
also works as long as it's at the start of its own line.)[[ Cat | domestic cat ]]
into [[Cat|domestic cat]]
a [[Dog|dog]] and two [[Cat|cats]]
into a [[dog]] and two [[cat]]s
.[[José González|Jose Gonazales]]
should be [[José González]]
, unless there is a very good reason for the piping, e.g. because the usage is in a direct quotation. This is a substantive change.<i>...</i>
with ''...''
, etc.<blockquote>...</blockquote>
to {{
blockquote|...}}
). The templates have additional parameters that provide features, often have custom
CSS styling for a consistent appearance, and often CSS classes for treatment in custom
user stylesheets.''...''
or '''...'''
with
Semantic HTML templates {{
em|...}}
or {{
strong|...}}
respectively (these use the underlying <em>
and <strong>
elements). This should not be done when the markup is simply conventionalized, non-emphasis, visual formatting, like italics for
titles of works or boldface for
pseudo-headings. Switching to semantic markup is a substantive change.{{
Use DMY dates}}
or {{
Use MDY dates}}
at the top of the article; or if there isn't one, the DMY or MDY date format that already dominates in the article (not YYYY-MM-DD format); or if it's a completely random mess, to whichever makes the most sense for that article (e.g. American MDY format if the subject has
strong ties to the US, but probably DMY format otherwise). If in doubt, open a discussion on the talk page about what date format to use. Date cleanup is a substantive change.
|access-date=
and |archive-date=
.]...
instead of the precomposed …
Unicode character", and "in measurements, put a space between the numerical measure and its unit symbol", that have something to do with how things are in the wikicode, but this list is not going to enumerate them all, as they are really about content not code per se (and doing so would essentially be duplicating the MoS, in a page that is meant to be a quick reference).<
syntaxhighlight lang="wikitext">...</syntaxhighlight>
(changing the lang
value to whatever is needed for the code type in question). This is a substantive change.
[1]==Heading==
level-2 markup, and subheadings proceed in order, level-3 ===Sub-heading===
through (at least in theory) level-6 ======Sub-sub-sub-sub-heading======
, without intervening levels skipped. (An article actually using all 6 heading levels probably needs to be restructured better.)
=Title=
, are not used in articles. A =Title=
corresponds to <h1>Title</h1>
and is reserved for the auto-generated article title. Some non-articles use =Heading=
anyway, usually maintenance pages that are transcluding multiple entire other pages, and usually should be left alone in this regard. But in an article, a =Heading=
error should be converted to ==Heading==
, with adjustment to any sub-headings that are topically under it, as needed.==Heading==
followed directly by ====Sub-sub-heading====
, convert the latter to ===Sub-heading===
, and adjust any further-nested heading levels under that, as needed.[[Wikipedia:Biographies of living persons#Subjects notable only for one event|one event]]
not [[WP:BLP1E|one event]]
; use {{
crossref|pw=y|See also {{
section link|Wikipedia:Manual of Style#Dashes}}}}
, not {{
crossref|pw=y|See also [[MOS:DASH]]}}
.
The following are generally not constructive, and range from pointless wastes of time, through annoying or controversial, to disruptive and problematic:
== Heading ==
to ==Heading==
or vice versa, other than to simply make them
consistent within the same article. Neither format is preferred by consensus.* List item
to *List item
or vice versa, other than to simply make them consistent within the same article. Neither format is preferred by consensus.[[Cat|domestic cat]]
piped links into lower-case [[cat|domestic cat]]
. This serves no purpose of any kind and actually makes it harder to notice a piped link when visually scanning the code.{{Template name|...}}
to {{template name|...}}
or vice versa. This serves no purpose of any kind.{{citation needed|...}}
with a shortcut like {{
fact|...}}
or {{
cn|...}}
. Over the years, Wikipedia has consistently been renaming all templates (at least those with any usage in mainspace) to be at descriptive, sensible names for the benefit all editors, especially new ones. Using shortcut versions makes it more difficult to know what issue is being flagged. And we have a bot that goes around replacing the shortcuts for this sort of template with the real template name anyway, so doing it is futile. (But no one cares all that much if you insist on using the shortcut version to begin with. Just expect it to be replaced.)
{{
harvp}}
has a much longer real name ({{
Harvard citation year brackets}}
) and having this appear numerous times throughout the article would not be helpful to anyone. Similarly, the {{
"'"}}
shortcut shows exactly what that template does, but it cannot actually have that as the page name for technical reasons; its long name {{
Double+single+double}}
isn't useful in the article's wikitext.[[Franklin Roosevelt]]
to [[Franklin D. Roosevelt]]
or [[Franklin D. Roosevelt|Franklin Roosevelt]]
just to "fix a redirect". However, it is perfectly acceptable to change it to [[Franklin D. Roosevelt]]
if for some reason it is preferred that "Franklin D. Roosevelt" actually appear in the visible text. Editors should also not change
redirects with possibilities like [[Journal of the Franklin Institute]]
to [[Franklin Institute#Journal of the Franklin Institute|Journal of the Franklin Institute]]
, so that readers arrive at the more pertinent article in the eventuality that it is created."
[[Kesha]]
to her sometimes-used marketing sylization via [[Kesha|Ke$ha]]
or [[Ke$ha]]
just because you think it looks cool; changing [[Sony]]
to [[SONY]]
or [[Sony|SONY]]
to mimic their logo; etc.<
syntaxhighlight>
, see
mw:Extension:SyntaxHighlight, and in particular its link to the list of supported languages of the underlying Pygments syntax-highlighting library at
https://pygments.org/languages/ (see the "Short name(s)" column).