2

As per title, consider some code which produces some output to STDOUT, what is the recommended way of formatting it.

For example, in Python, you could write:

print('Hello World!')

which produces the output:

Hello World!

What I typically do is to either put this in a comment:

print('Hello World!')
# Hello World!

or have it within separate code fences with the none language tag:

print('Hello World!')
Hello World!

Sometimes I have seen it as a quote, e.g.:

print('Hello World!')

Hello World!

Is there a better way of formatting the output of some code? What is the recommended way?


Given the frequency of this, I think there should be a standard way of formatting it. The currently available options seems to be non-ideal, i.e.:

  • the commenting solution does not make it clear enough that what is commented is actually the output
  • the separate code fences solution makes it hard to tell apart code from non-code blocks, and it is harder to edit when multiple outputs are to be shown
  • the quote solution do not use a monospace font which is the typical choice for console output, ignores newlines (and it is also hard to edit when multiple outputs are to be shown)

EDIT

A possible interesting approach would be to have a output or stdout language tag for longer output. This could additionally be paired with some specific sequence for marking a certain comment as output comment, such that e.g. comments starting with a # (on top of the language-specific commenting mechanisms) are formatted as output, e.g.

## this should display as output in Python
//# this should display as output in C++
7
  • 2
    That's opinion-based. Some prefer quote (to better distinguish between code and output) and some prefer code (less formatting work, horizontal scrolling and monospace). I personally use quote and only code formatting for Java exception stacktraces due to their long lines which won't work in quote blocks.
    – Tom
    Oct 15, 2019 at 13:34
  • 1
    a output language tag or similar changing the background would partially address the shortcoming of the separate code fences solution.
    – norok2
    Oct 15, 2019 at 13:36
  • "the commenting solution does not make it clear enough that what is commented is actually the output" Certainly, since it's a comment already, you can add more to the comment, like # outputs Hello World? Also, you can combine quote and code fences: > ~~~ before and after the code. Not saying it's a great look (I personally don't like it), but it knocks off two of the negatives... Oct 15, 2019 at 13:41
  • @HereticMonkey > ~~~ can surely be done, but that is an ugly hack, and so is adding extra comments to the commenting solution. An extra language tag would allow for beautiful and content-specific formatting (e.g. reducing/removing the blank space between the code and the output, changing the background, having different background for stdout or stderr, etc.).
    – norok2
    Oct 15, 2019 at 13:50
  • "the commenting solution does not make it clear enough" - I disagree. You have to be pretty out there to not work out something so trivial. Effectively you're mimicking what would happen if you would invoke the line of code in an interpreter / shell - perfect.
    – Gimby
    Oct 15, 2019 at 13:50
  • This would not mix well with additional comments one may want to have in the code. Also, if you compare what say the standard Python interpreter offers vs what IPython offers, you can immediately see that one of its greatest advantage is making a more clear separation between the input and the output. I would agree that the commenting is the best that we have at the moment, but not the best that we could have.
    – norok2
    Oct 15, 2019 at 13:55
  • 1
    I think you should amend your question to specifically ask for the different formatting for output blocks. Currently, Stack Overflow uses Google's Prettify to format code blocks. AFAIK, there are none for "output". Oct 15, 2019 at 13:55

0