38

Every day I leave comments on the site asking users to fix their code formatting, or notes that I have already done so. True, a lot of it comes down to apathy (or lack of consideration) on the part of askers, but after some examination I have come up with several ways that the process can be smoothed out. My goal here is to reduce the amount of accidental errors in posting code, and/or misunderstandings of how the formatting works.

  1. I have lost count of the number of times I have seen stray enter code here text in questions. The problem has been known about for a long time. I propose a different solution: instead of trying to detect when this happens, just don't add the text, under any circumstances. Instead, position the caret after adding text to the post. The "enter code here" text is not helpful UI-wise, because the user just finished consciously choosing the option.

  2. Indented code blocks are awful. They are inferior to code fences in almost every conceivable way: they don't allow for specifying a language; they don't neatly delineate the code; they require blank lines before and after the block (and this is not explained either on the post form or in the formatting help); and they require extra space to be added in front of each line of the block (which is to say, they are much harder to do manually, and are the source of ungodly amounts of questions with misindented code); and they need an extra hack to work with numbered or bulleted lists (this is explained on the form if you recognize the help menu, which is not at all obviously recognizable as a help menu; it is not explained in the formatting help.)

The "each line" problem is especially bad because if you have an indented line of code and hit return, the next line is not auto-indented (as typical IDEs would do). So if you don't have code to paste, you're slowed down when typing it in manually.

Worse yet, code blocks make a lot of real-world code look almost right (because the bulk of the code is indented at least one level, and four spaces is a commonly used indent), making it harder for OP to realize the mistake, and making it harder for answerers to notice that the original code does, in fact, have the appropriate imports etc.

The system should use fences when the button is clicked, and labelling the current behaviour as "by design" is absurd. It's even worse because the {} button can't even be consistently used as an "indent" button - if all the selected lines are indented, it will dedent instead. This is a misfeature because 1) it is inconsistent and 2) there is already an undo function.

Oh, and if code fences are used, clicking the button on a blank line with no text selected allows for just adding the fences. With a code block, you have to indent four spaces, and then either not leave a printable character as evidence, or (as actually happens) write the dreaded enter code here text.

  1. There are many common patterns of failure that could be automatically detected. One is attempting to use an inline code span for each line of code:

def like_this():

# and this

# and this

Another is trying to paste an entire multi-line code as an inline block:

def like_this(): # and this # and this

Another is trying to put code fences on the same line of the code (check the source for the post; notice how this type of error hides actual code completely, and breaks the rest of the post):

    # and this
    # and this```

All of these could be detected by regex, and the latter two could be mitigated by checking what is on either side of the caret when text is pasted into the form.
14
  • 22
    I almost reflexively fixed the end of your post after having seen this so many times...nice touch :-)
    – Ryan M Mod
    Commented Jun 1, 2022 at 3:56
  • 1
    Meh. I strongly prefer indented code blocks to code fences. The real problem there is Python. The blank lines and the indentation are more than sufficient to delineate the code. Requiring blank lines is obvious; in Markdown, the Markdown is supposed to be readable, not just the formatted output. Specifying a language can be done just about as easily as code fences, but differently. It is covered in the documentation. And, yes, it requires adding extra spaces to the lines. So what? Easy to do manually (I do it all the time), or by selecting all and clicking the toolbar button.
    – Cody Gray Mod
    Commented Jun 1, 2022 at 4:06
  • Fences actually create the problems described in your #3, which were never problems before fences were introduced as an option.
    – Cody Gray Mod
    Commented Jun 1, 2022 at 4:06
  • 3
    The first two problems in #3 were always there, because they come from inline code spans. Adding extra spaces to each line is tedious and error prone, both from personal experience and from noticing patterns in wrongly formatted code in the Python tag. It is very common for people to indent only the first line, and I can't help but assume this is because they think that's how it's supposed to work. Indented text doesn't intuitively connote "preformatted text" to me; it connotes "block quotation" (even though we use > for that). Commented Jun 1, 2022 at 4:11
  • 5
    @CodyGray as much as it is a rare occasion, this where I support Karl's position. You are definitely right that whitespace indentation is fine (and can even be preferred), but for the sake of being pragmatic, I'd say fences have more sense - we both know that the main cause of the issue are users who never even heard of the spec, do as little as possible to format their code, and, in general, seem to be incapable of more than clicking on buttons (many times not even that). This creates a ton of busywork, f.e. filling the suggested edits queue with "formatting" edits that are often [1/2]
    – 0Valt
    Commented Jun 1, 2022 at 4:21
  • 2
    [2/2] no better than the original (and some manage to make it worse). In turn, this creates even more busywork for reviewers, and, subsequently, to those who are watching the watchers. One of the many issues with formatting with whitespace is broken code blocks because users can't be bothered to look at their post twice (granted, SE's UI obsession to make as little use of available screen space as possible does not help, but that's another matter) has consistently been the source of wasting time of editors and reviewers alike for years now.
    – 0Valt
    Commented Jun 1, 2022 at 4:25
  • 3
    @OlegValteriswithUkraine Indeed. based on what I see in the previous questions that I linked, people will complain it "only enables the help vampires", that this stuff is posted by people who don't care anyway, that the suggested edits are futile, etc. I disagree with them, from my experience; there are plenty of questions where poor code formatting is the only sign of not caring, and everything else suggests that OP just can't figure out what is missing (or extra) in the post. Poor code formatting is consistent with that mindset; the preview can be skipped over easily enough. Commented Jun 1, 2022 at 4:32
  • 6
    I strongly prefer code fences. Specifying the language for indented code blocks is awkward and non-standard. Indentation creating code blocks also creates the problem of people pasting code and not noticing that they failed to make the first and last lines of a block into code, because they see a code block. It also causes problems with the many, many editors who use the conventional way with code fences to add syntax highlighting, resulting in edits that add incorrect indentation to every line in a code block (and I don't have time to reject all of them).
    – Ryan M Mod
    Commented Jun 1, 2022 at 4:38
  • 1
    I think your observation is correct, @KarlKnechtel. I am an active suggested edits reviewer, and from what I've gathered so far, the quality of posts with ill-formatted code because of whitespace indentation varies wildly (we also need to keep in mind that the issue plagues answers just as much as questions). There are those that are beyond salvation, and no amount of changes would help them, but there indeed are those (and an insubstantial number, I might add) that get tricked by the caveats of properly indenting with whitespace.
    – 0Valt
    Commented Jun 1, 2022 at 4:40
  • @RyanM While I also prefer code fences, I'm afraid people are just copying their code as-is, and it is identified as code block just because it is indented. And if we didn't have that, it would be even harder to read. Commented Jun 1, 2022 at 5:34
  • 7
    There is simply not adequate support in the editor to fix up messy posts which have been indented. I often have to copy and paste things into a local editor to sort them out, if I’m feeling generous. Code fences using backticks are vastly easier to clean up in my view.
    – user438383
    Commented Jun 1, 2022 at 6:14
  • Code fences are against the "down" in (the original) Markdown (minimal visible markup content—e.g., readability of the source), but the new syntax highlighter (and/or how it is implemented) leaves no choice but to use code fences (as the alternative would be even more complicated). Most posts, new or old, now need explicit syntax highlighting hints (in the parts that are not in main tag's programming language) in order for the new syntax highlighter to not mess it up. Commented Jun 1, 2022 at 11:39
  • I prefer code fences except for inline monospaced text. Having to prefix with 4 spaces is awkward and while I got used to writing code samples in-editor for a long time that way.... it's nice to be able to align the code text to the far left with everything else. Makes copy/paste quite a bit easier, too.
    – codewario
    Commented Jun 1, 2022 at 15:24
  • 3
    To be fair, while the behavior of de-indenting indented code might feel inconsistent, it's incredibly useful when fixing such formatting mishaps, precisely because it de-indents. When fixing indents in a post or converting from indent to fence notation, being able to Ctrl-K away the indent instead of copy-pasting the code into an off-site editor is a godsend. Otherwise, I'm fully in support of replacing the indent behavior of the current editor. Worth noting that the new editor (despite its own horrors) does use fence notation.
    – zcoop98
    Commented Jun 1, 2022 at 17:45

0

You must log in to answer this question.

Browse other questions tagged .