User:SMcCandlish/Helpful and unhelpful code changes

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.

Helpful changes

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:

• Removing blank lines between list items in wikicode lists. This helps accessibility and document structure in general. When a list is built with *, #, 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.
• [MOS:DLIST - write up an item about this.]
• Changing two blank lines in the source to one; this actually does improve the visual output of the page, by removing an unnecessary block of whitespace. Fixing this is a substantive change.
• Moving old stub templates from below the categories to just above them (and their {{DEFAULTSORT:}} if any), below any navbox or other content. Categories should always be the last thing on the page.
• Moving {{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.
• Adding one blank line above any stub template to separate it from other content; these templates are made to stack up close to each other if more than one is used, but this means they also butt up against any other content that preceded them. Since this fixes a visual display problem, it is a substantive change.
• Removing unnecessary blank lines (not linebreaks) between page-top templates such as {{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.
• Removing unnecessary blank lines above or below images.
• Moving citations out of block quotations and pinning them to the end of the sentence that introduces the block quote; they are not part of the quoted material. This is a substantive change.
• Formatting citations for readability in the style {{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.
  • Especially fix confused formatting like {{cite book| last=Smith| first=Jane B.| title=Breeding Weasels| date=2023| ...}}, which adheres the parameter-opening | to the data of the previous parameter.
• Formatting <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" />
  • The double-quote marks are required any time a parameter value contains a space, punctuation, or any alphabetic or other character outside the original ASCII text range (which means most letters with diacritics or not in the Latin character set). Few editors realize or remember this and are apt to do invalid things like <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.
  • The spaced  /> is understood by more parsers than the version without, so this is better for reuse of Wikipedia content.
• Replacing <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.)
• Removing pointless spaces from inside wikilink code, e.g. change [[ Cat | domestic cat ]] into [[Cat|domestic cat]]
• Compacting redundant piped links, e.g. change a [[Dog|dog]] and two [[Cat|cats]] into a [[dog]] and two [[cat]]s.
• Replacing unhelpful piped links with bare ones. A common case of this is jingoistic suppression of diacritics: [[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.
• Replacing bare HTML markup with the wikimarkup equivalent if there is no special functionality provided by, or other particular reason for, the HTML version (e.g. replace an HTML table with a wikimarkup table; replace an HTML list with a wikimarkup list, replace <i>...</i> with ''...'', etc.
• Replacing bare HTML markup with a templated equivalent (e.g. change <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.
• If italics or boldface represent semantic emphasis (as in "Provenience is not the same as provenance"), replacing wikimarkup ''...'' 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.
• Normalizing dates to all use the same format, per MOS:DATEVAR. This does not mean switching a consistent or mostly consistent date format to one you like better. It means normalizing recently added stragglers to match the date format declared with {{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.
  • [Something here about the long-running dispute about ISO dates being used for |access-date= and |archive-date=.]
• Cleaning up material to comply with the WP:Manual of Style. There are numerous MoS rules, like "use straight quotation marks, not curly ones", "use ... 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).
• [WP:LINT - write up an item on this. Include both invalid tags and unclosed ones.]
• Peripherally related: syntax highlighting: When illustrating complex code in the rendered output, it is helpful to most readers (including internal ones, i.e. editors) to wrap the code examples in <syntaxhighlight lang="wikitext">...</syntaxhighlight> (changing the lang value to whatever is needed for the code type in question). This is a substantive change.
• Heading-level repair: Headings begin with ==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.)
  • Level-1 headings, =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.
  • If a level has been skipped, e.g. ==Heading== followed directly by ====Sub-sub-heading====, convert the latter to ===Sub-heading===, and adjust any further-nested heading levels under that, as needed.
• Replacing shortcut links in our documentation to instead use the actual page and section names they go to: Use [[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]]}}.
  • Shortcuts are for editor convenience on talk pages and in the URL bar, not for informing editors (often new ones) where and what our important documentation is. People absorb shortcuts slowly over time; they should not be forced to memorize hundreds of them their first week to even understand what the rules are and what pages contain them.
• And the inverse of anything listed in "Unhelpful changes", below.

Unhelpful changes

The following are generally not constructive, and range from pointless wastes of time, through annoying or controversial, to disruptive and problematic:

• Switching == Heading == to ==Heading== or vice versa, other than to simply make them consistent within the same article. Neither format is preferred by consensus.
• Removing or adding a (single) blank line between a heading and the content that follows it, other than to simply make them consistent within the same article. Neither format is preferred by consensus.
• Switching * 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.
• Adding or removing an optional blank line before and after block elements like tables, block quotations, lists, etc., other than to simply make them consistent within the same article. Neither format is preferred by consensus.
  • For all four of the above change types, the argument in favor of them is slightly increased readability, while the argument against is slightly more concision, and neither argument seems to overpower the other.
  • For all four, the spaced versions are eventually going to "win" for the technical reason that they are enforced by VisualEditor. Test this and make sure this is correct.
• Turning horizontal citations or most other templates into vertical ones within the article lead or body. This is very visually disruptive to the flow of the article content, makes it much more difficult to discern paragraph structure, and induces a great deal of unnecessary vertical scrolling. However, aside from article-body citations, very complex templates with a large number of parameters, like infoboxes, are usually presented in vertical format, as often are citations when given in "list-defined references" format at the bottom of an article.
• Changing the order in which two or more citations are cited for the same claim, simply to make their displayed numbering be in order. This is unmaintainable because the citations and the content they support may be moved around by other editors at any time. It is much better for multiple citations to be in the order of decreasing strength and pertinence: put a secondary citation like a literature review in front of a primary one like an original journal paper (a citation to which is usually not even necessary but might be provided for the benefit of expert readers); put a strong secondary source like a book by a subject-matter expert ahead of a weak secondary one like a magazine article.
• Changing [[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.
• Changing {{Template name|...}} to {{template name|...}} or vice versa. This serves no purpose of any kind.
• Replacing a cleanup/warning template's real name like {{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.)
  • None of this typically applies to utility templates for formatting, citation, and other functions; e.g. {{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.
• Changing shortcuts in our documentation from "WP:FOO" format to disused variants, such as "wp:foo", "WP:foo", "wp:FOO", "WP:Foo", "Wikipedia:FOO", etc. It is the essentially universal convention to use "WP:FOO" style for these things, and even if you prefer not to, no one else cares to join you.
  • Relatedly, there is no reason to go around creating "WP:foo" shortcuts that correspond to "WP:FOO"; virtually no one is going to use them, and doing this simply increases redirect maintenance load for no good reason. Most especially do not create unused alternatives to the "MOS:FOO" pseudo-namespace convention, like "mos:foo", "MoS:Foo", "Mos:FOO", etc. – all of these things actually live in mainspace, and only "MOS:FOO" is tolerated (various alternatives are routinely deleted at WP:RFD). Do not create imaginative new shortcuts of the "MOS:" type that are not actually needed. All of this also goes for other pseudo-namespaces like the disused "C:" and "T:" and "P:"; they'll all be mainspace clutter that may eventually collide with a title needed for an actual real-world subject.
• "Fixing" redirects that are not broken. To quote from the guideline: "editors should not change, for instance, [[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."
  • There is an unwritten consensus that it is fine to replace a redirect if it is a "substandard" name (perhaps being used contextually for a specific reason, e.g. in a direct quotation), or is a term/name for a subtopic that certainly should never have a stand-alone article and will probably always redirect to the present target (e.g a minor character in a video game that goes to an entry in a list of such characters, especially if it was forcibly merged there by an AfD or other consensus discussion).
• Piping a link or switching to a redirect just to get a spelling (or completely different name) that is not the most common and is not somehow more appropriate in the present context than what the article title is. E.g.: changing [[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.
• And the inverse of anything listed in "Helpful changes", above.