13

My primary question is

What is the preferred method for formatting code?

followed by

Is the formatting help at odds with the preferred formatting method?

The sidebar for the "Ask a question" interface currently looks like this:

The first two bullets describe how to format code with fences. The sixth describes how to do it with spaces.

Notice that "indent code by 4 spaces" is still there. However, you could be forgiven for not noticing it.


Historical Context

When I first started asking questions on Stack Overflow, I believe the sidebar recommended something else for formatting code. My best guess is that it recommended something like <pre> tags:

You can still format code using tags that can't be used in the code itself!
Who knew?

So I actually don't remember exactly what was the method highlighted in the sidebar at the time. I just remember that the very first thing that happened after I made my first post was that someone edited the post to remove the recommended formatting method and indent the code four spaces. At the time, I was startled, to say the least. However, I got the hint and ever afterward used four spaces to indicate code.

I was startled because the community's preferred method of formatting code contradicted the formatting help. A problem that still seems to be happening today.

Today, I was curious about the new "Ask a question" interface, so I decided to have a look at it. I was startled to see this:

First bullet says to format code with fences. There is no mention of using spaces.

Why is the official Stack Overflow code formatting help at odds with the accepted conventions?

I am not requesting that backticks be supported. I am asking

  • Which code formatting convention is preferred?
  • If four spaces is preferred, why doesn't the documentation reflect this?
  • If neither format is preferred, why are backticks more heavily emphasized in the help shown to new users and question askers?

I am not asking about inline backticks. I am asking about

```
backticks used to format code
```

versus

    spaces used to format code
17
  • 3
    In brief: happily, fenced code blocks actually work now. As for being the preferred method, I feel it makes sense, as they are less fiddly than the four spaces method.
    – duplode
    Commented Jul 27, 2019 at 2:01
  • The only thing it shows is that everyone forgets what the formatting help looked like years ago. If you were a new user to the site then, the help recommended using a formatting convention that every other user had to tell you to stop using. It was surreal.
    – user3657941
    Commented Jul 27, 2019 at 2:18
  • 2
    @DavidCullen I don't think there is a strong preference either way; in any case, it doesn't seem to be a settled matter. Ctrl+K and the toolbar button still add four spaces. Relevant: Should we make the {} button add ``` instead of four spaces?
    – duplode
    Commented Jul 27, 2019 at 2:33
  • Did Stack Overflow ever support another method for indenting code? Something like [code] tags?
    – user3657941
    Commented Jul 27, 2019 at 2:44
  • @David Yup, you can actually indent code in posts with <pre> code </pre> HTML tags. It's been supported (though not suggested) for as long as I remember, which extends back to about 2015. I know it works in posts, although I'm not sure about comments, so I'll give that a try: <pre> This is inside a pre-formatted block </pre> ... Looks like it didn't work, probably because HTML is deactivated in comments.
    – Davy M
    Commented Jul 27, 2019 at 2:46
  • 2
    ...someone edited the post to remove the recommended formatting method and indent the code four spaces... Assuming all of your code was properly formatted and did not cause any other issues with your post, they should not have done that. There are certain ways of formatting code that play nicer with other formatting (putting code in an unordered list for example) but there isn’t a preferred way that you’re supposed to use.
    – BSMP
    Commented Jul 27, 2019 at 3:35
  • I have raised the issue of both ways of making code blocks showing up in that sidebar in a separate question.
    – duplode
    Commented Jul 27, 2019 at 15:15
  • 2
    I don't know whether to laugh or cry. Why is "primarily opinion-based" a close reason on meta?
    – user3657941
    Commented Jul 27, 2019 at 15:50
  • @David I say this is a case of something to laugh at. The POB close reason exists on Meta for posts that cannot have an objective answer (even though there are certain subjects where opinions do matter to the functionality of the site so they get through, but your's isn't like those): "...but answers to this question will tend to be almost entirely based on opinions, rather than facts, references, or specific expertise." However, you are explicitly asking for the preferred method, meaning one that's supported by references, not people's opinions as to which should be preferred.
    – Davy M
    Commented Jul 27, 2019 at 16:00
  • 2
    In this case, the answer is "There isn't one, code fences or 4 spaces are both fine." The reason for showing one more obviously than the other is also possible to answer objectively, since the Stack Overflow employees who worked on it could answer and say why. So POB is not a valid reason to close your question, and you should laugh at it.
    – Davy M
    Commented Jul 27, 2019 at 16:02
  • 1
    Does Stack Overflow the Company have a preference? I guess I should really ask that as a separate question, but this is as much fun as I can handle for now.
    – user3657941
    Commented Jul 27, 2019 at 16:13
  • 3
    I've seen far more instances of people fubaring code fences than indenting. With code fences, I've seen them using the wrong quotes, and attempting to combine them with indenting which is more work to manually fix. Personally, I'd rather people use indenting and have code fences nixed altogether. I personally don't see any point to code fences. Commented Jul 27, 2019 at 20:08
  • Case and point: stackoverflow.com/q/57235714/3000206 Commented Jul 27, 2019 at 20:13
  • 1
    @DavidCullen if SO themselves had a preference, wouldn't they have just enforced it and removed the alternative?
    – VLAZ
    Commented Jul 29, 2019 at 6:50
  • 1
    If you're using spaces it's a lot uglier and non-standard as you have to use some archaic SGML comment like <!-- language: xxx --> or <!-- language-all: xxx --> rather than communicating the information with a CommonMark info string. Moreover, it's less likely to be supported upstream with other tools (eg., Github, GitLab, BitBucket, etc). It's also more likely to cause problems with HTML serialization, and it's far more ugly to read as text. Generally, for the people that care the standard code-fence with info string provided by CommonMark (shown above) is a better option. Commented May 19, 2021 at 4:01

2 Answers 2

17

Between fenced code blocks and indented code blocks, I don't think there is a strong preference either way (at least, not yet), so no one is going to be bothered by your choice on that. It is worth noting that both CTRL+K and the toolbar button still produce indented code blocks (for the feature request to change that, see Should we make the {} button add ``` instead of four spaces?).

If neither format is preferred, why are backticks more heavily emphasized in the help shown to new users and question askers?

Presumably because they tend to be less fiddly than indented code blocks, not requiring changes to the Markdown lines with the code. Another advantage is that with fenced blocks you don't need an HTML comment to change the syntax highlighting.

(By the way, that the Ask a Question sidebar also says "indent code by 4 spaces" is probably a mere oversight.)

12

TL;DR: Favor fenced code blocks. Like... always.

Might read like opinion, but there's rationale to it, too. On cursory look using either one (code fences or indentation) will have identical effects. So why even care?

I've been pondering about this for while now, and there are in fact differences, subtle, yet with surprising consequences. Code fences satisfy a lot more formatting needs than indentation can. And they are easier to use, too!

Ergonomics

Code fences allow an author to copy-paste code, verbatim. No need to (artificially) indent the code in a code editor, just so that it shows up properly when translated to Markdown. This holds true when initially publishing a contribution, as well as when editing it, so translating a contribution into a format that's easier to edit is an improvement.

There's one unfortunate downside: Depending on the keyboard layout used, the backtick key can be a dead key requiring additional key presses to enter an odd number of backtick characters. That's a one-time investment, though, and if you've written bash scripts in the past you probably don't even perceive it as an investment at all.

There's another ergonomic aspect: The web-based editor has a fairly narrow fixed width. Horizontal space is precious, and using up any of that will inevitably higher the chances of the editor breaking lines of code apart. Navigation suffers, both by keyboard and eye. Fenced code blocks do not use up any of that space for formatting, making it less likely to run into this usability issue.

Syntax highlighting

Code fences allow for specifying a syntax highlighting hint (info string). Using indented code blocks one would need to drop out of Markdown down to HTML comments to specify what language the following (or all) code block should be rendered as.

```cpp
/* Some code */

is far more concise, obvious, and less cluttery than

<!-- language: lang-cpp -->

    /* Some code */

The latter isn't only more verbose, it's also creating a dependency on a particular Markdown renderer implementation. Stack Overflow switched to CommonMark, improving interoperability by agreeing on a common specification. Promoting the latter is leaving an opportunity on the table (see also this comment).

There seems to be a popular opinion that "a language indicator [were] redundant". This assumes that the heuristic used to detect languages works reliably (it doesn't), and will not change over time (it has). If you want to make sure that code renders as desired, and continues to render as desired over time and across different tools, a language tag is required.

CommonMark has a standard feature that suits itself for this purpose (info string). That feature is unavailable for indented code blocks.

Vertical separation

Occasionally it is desirable to provide related, yet distinct portions of code. A C developer may want to post a header followed by its implementing compilation unit, e.g.

/* source.h */
void foo();
/* source.c */
void foo() {}

I'm not aware of a way to produce the identical rendered result in Markdown alone using indentation.

Nitpicker's Corner: It is possible to achieve it by placing an empty HTML comment between the two indented blocks, but this is rather a hack and is certainly not obvious to someone unfamiliar with the intricacies of Stack Overflow's Markdown rendering. The solution with code fences is much more obvious and intuitive.


Recommendation

When authoring new contributions, prefer fenced code blocks with an info string over indented code blocks. It's the only syntax available in CommonMark that supports an author in conveying the desired syntax highlighting applied.

When performing or reviewing edits that change from indented code blocks to fenced code blocks, make sure the following requirements are met:

  • Edits remove the (now) redundant spaces.
  • Edits include a language tag.

Reviewers can choose the "Improve Edit" option to install those requirements when missing. Extra bonus if you apply vertical spacing as desired.

I will even go one step further and say that an edit that replaces an HTML-comment style language hint with a fenced code block plus info string is an improvement. It both improves interoperability and future-proofs a submission by making it resilient against changes in language detection heuristics.

34
  • 1
    I think the syntax highlighter takes tags into account when no language is provided, which should get it right 99% of the time. But I do agree with you. Fences are easier to type out, less prone to horizontal scrolling on long lines, don't require hacky-feeling comments, etc. Not worth editing a previously-fine post, though.
    – GammaGames
    Commented Jul 6, 2021 at 16:58
  • 19
    These advantages are irrelevant when it comes to editing a question that's already posted with correct syntax highlighting. Edits that only change from one to the other are, by definition, "no improvement whatsoever" (to how the post is displayed, because it doesn't change how the post is displayed). Unless one is officially marked as deprecated, that is, but even then, going around editing posts only to change that is probably not desirable. A language indicator is redundant (and should thus not specifically be edited in) when the syntax highlighting is correct due to the language tag. Commented Jul 6, 2021 at 17:02
  • 3
    I agree that fences are objectively better, but I also think the only sensible edit policy is one that makes the fewest changes necessary to make a post intelligible. If the original post reads and parses correctly, don't mess with it. This is one reason I often reject edits that use garbage like Prettier to reformat someone's code: if indents are incorrect, fix that, but don't mess with their quote marks, use of spaces, etc. Try to preserve the original poster's voice and choices, even if they are bad, unless they prevent the community from engaging. "Do the least harm."
    – Tom
    Commented Jul 6, 2021 at 17:26
  • 13
    I am strongly of the opinion that one should not make edits which change a post from one valid representation to another, just because the editor likes the other representation or thinks it's "better". This applies to different Markdown representations, different dialects of English (e.g. American English vs. British English vs. ...), different indenting styles, etc. In particular, I strongly disagree that we should be recommending that an edit be made or approved which just makes that type of change, which is what this question is about.
    – Makyen Mod
    Commented Jul 6, 2021 at 17:26
  • 8
    Deleted a bunch of now-irrelevant comments. I'd already gone to sleep by the time you posted this answer, but I agree with Makyen's assessment that it doesn't change the dupe status. However, I do think this is a good answer with very good points. Furthermore, while I do agree with Makyen that we cannot in good conscience permit only a single A to be posted to a Q closed as opinion-based, I go one step further and say that closing a Q like this as opinion-based (esp. on a Meta site) is silly. So, I've reopened it and merged in your answer. Feel free to flag this comment once you've read it.
    – Cody Gray Mod
    Commented Jul 7, 2021 at 4:07
  • 1
    @mak "I strongly disagree that we should be recommending that an edit be made or approved which just makes that type of change" - Why? Now that I've updated this answer and provided rationale for why this change is an improvement (even if invisible), why would you reject this sort of improvement? What's the sort of improvement you would not reject? And what makes one improvement more accept-worthy than the other? Commented Jul 7, 2021 at 8:43
  • @IInspectable Even if you were right that code fences would be better, the potential gain from such an edit would never outweigh the disadvantages of an edit, amongst other things cluttering the active question page with posts which don't need additional attention and taking this attention away from other posts who deserve their spot on the active question list or causing extra work for the people doing reviews. Commented Jul 7, 2021 at 8:52
  • 4
    @sam I feel this is just voicing an (alarmingly accepted) cultural trend: We're constantly allowing technical debt to accrue when addressing it doesn't have any immediate benefit. Something we will have to deal with, at some point. Better sooner than later. Sure, edits aren't invisible, though at only 2000 reputation, a user's edits will not contribute to any review queues, so that's eventually a non-issue. Commented Jul 7, 2021 at 9:28
  • 2
    @sam "only changing from one code markup to another" - That fails to appreciate that I'm not suggesting to go from one arbitrary representation to another arbitrary representation. I'm suggesting to go from a representation that's either not self-describing or out-of-spec to a representation that's conforming to CommonMark, and fully self-contained. We can probably agree that the benefits are real, but won't agree on the amount of "noise" admissible in getting there. That's fine, though, Meta is there to discuss these things after all. Commented Jul 7, 2021 at 10:17
  • 4
    @IInspectable "Something we will have to deal with, at some point" - what? Why? There's currently no indication that the space-indented variant will ever become unsupported. And if SO ever decides that they want to do away with that syntax, they could just write code which migrates the old posts by transforming the spaces-based syntax to the fence-based one (should be trivial if you have access to their current markdown parser). I see absolutely no reasons to stipulate mass edits of a perfectly valid format because you fear things that might happen in the future.
    – l4mpi
    Commented Jul 7, 2021 at 10:22
  • 1
    @l4m "what?" - I was referring to a culture where short-term economic goals inhibit addressing technical issues with long-term consequences. "I see absolutely no reasons to stipulate mass edits" - I wasn't recommending mass edits. I was making a point that the two alternatives we have for formatting code aren't actually equivalent in their features. If you are editing a contribution or reviewing one you now know how they are different, and can make an educated judgement call on whether to allow or reject that edit. Commented Jul 7, 2021 at 10:52
  • 2
    @sam "they both have their advantages" - I don't see any advantages of indented code blocks. The one example you make up is quite fabricated, and it can always be resolved by switching to tilde characters or an appropriate amount of characters. But I'm not arguing whether a hypothetical edit should be simple anyway. "indention has the advantage that one can already apply it in one's code editor" - That's not an advantage. That's one way to deal with a disadvantage of indented code blocks. And it's glossing over the fact that you have to go back and undo your changes when done. I mean... Commented Jul 7, 2021 at 11:42
  • 2
    @cha That feature has been requested already. Vote on it if you care enough. Commented Jul 7, 2021 at 12:49
  • 1
    @sam Please find me a question that contains ~~~~ in a way that will not allow you to wrap it inside a fenced code block using ~~~~. I've looked through several from the search query, and none were of that category. That's 955 questions, total, and I will be genuinely surprised if even 10% of them could not use fenced code blocks using ~~~~. We're talking like 100 (max) questions out of, what, 21.4 million? The chances of finding a question that's somewhat harder (not even hard) to translate to fenced code blocks is on the order of winning any given national lottery. Commented Jul 7, 2021 at 14:45
  • 2
    Thanks for the details and links about language heuristics not always working as expected. Also: language tag behind the fence backticks is optional, so people would still be free to omit it in obvious cases. Commented Dec 20, 2021 at 16:08

You must log in to answer this question.