43

Given a code-formatted table:

+------+------+
|  id  | name |
+------+------+
|  1   | Paul |
|  2   | Nash |
|  3   | Anne |
|  4   | Lily |
+------+------+

and its corresponding Markdown-formatted table:

id name
1 Paul
2 Nash
3 Anne
4 Lily

I always prefer the second one against the first one, for a very simple practical reason. If you need to debug code, and want to reproduce the tables in a private environment, and you attempt a copy-paste, the former one will give you the whole table skeleton you need to polish by hand (quite a bit of time if the table is big), while the latter one will allow you to copy data right away.

After having edited the table of a post (to the SO-format) for the sake of saving devs' (and my) time on the debugging step, I got a comment from a more experienced user (around 20k rep), claiming that my edit was not relevant and, in a later comment, that SO-formatted tables are poor with respect to code-formatted tables.

Am I missing something about it? What are the official SO guidelines?

Reference to the edited (and edit-rollbacked) question here.

8
  • 5
    At best it's preference. I would not suggest changing one for the other; if someone has posted their content as a well formatted text table leave it be. I, personally, prefer the former, as I find them easier to manipulate to DDL and DML statements.
    – Thom A
    Commented Jun 6, 2022 at 12:32
  • The user replied in the comments that he preferred my edit, though in first instance he didn't know how to use SO-formatting, which was the reason he decided to use backticks directly (as he was a fairly new user of this platform). @Larnu
    – lemon
    Commented Jun 6, 2022 at 12:35
  • 3
    I wouldn't recommend swapping one for the other just for the sake of it. If it's your answer - go ahead. If it's somebody else's - it's not really clear cut. One format might have advantage in some cases. E.g., I know some tools consume the first format, so changing over makes it harder to feed the data into those.
    – VLAZ
    Commented Jun 6, 2022 at 12:35
  • @Larnu Yes, it was exactly that question. My line of thought was "This problem is clear to me and I don't feel it needs large edits. First thing is to get data. I need to fix tables. Can I save others time too? Then apply a small edit that can improve the post." Just this.
    – lemon
    Commented Jun 6, 2022 at 12:41
  • 22
    From a screen reader accessibility standpoint the <table> is much easier to understand than the ambiguous block of pre-formatted text.
    – Henry Ecker Mod
    Commented Jun 6, 2022 at 12:44
  • 1
    You are misrepresenting what I said. See my answer post.
    – philipxy
    Commented Jun 6, 2022 at 14:18
  • 1
    I noticed that discussion and ... it was a storm in a teapot over nothing. In that particular question the best format was purely a matter of preference. But this question produced some gems - Python and R libraries can read HTML tables directly from the clipboard, making the HTML table format the best in some cases. Commented Jun 7, 2022 at 21:05
  • 2
    Why did you rollback the edit? If someone thinks, this edit should be revert, let them do the rollback. So now, we have no trace of the mysterious user who claimed “that SO-formatted tables are poor with respect to code-formatted tables”…
    – Holger
    Commented Jun 8, 2022 at 8:27

7 Answers 7

57

Code formatted tables are a poor user experience for some users. I think you can tell why:

plus six hyphens plus six hyphens plus vertical bar id vertical bar name vertical bar plus six hyphens plus six hyphens plus vertical bar 1 vertical bar Paul vertical bar vertical bar 2 vertical bar Nash vertical bar vertical bar 3 vertical bar Anne vertical bar vertical bar 4 vertical bar Lily vertical bar plus six hyphens plus six hyphens plus

Here's another example, without the decorations (from MySQL: Long table vs wide table):

id size price

1 S 12 dot 4 1 M 23 dot 1 1 L 33 dot 3 2 S 3 dot 3 2 M 5 dot 3 2 L 11 dot 0

That's what I hear when I use Voiceover, all strung together with no pauses. In contrast, the markdown table is much more navigable and parseable. There are shortcuts to navigate! The voice pauses between each cell! You no longer have to remember how many cells over you are from the end and what the headers are!

To better explain how navigation works, assume you're looking for a column with a specific value. In a code table you have to read all the values that come before the one you want, all while keeping track of where you are in the table and not getting confused with the other columns (can you imagine if you're looking for a number in a table where every value is a number?), so that's roughly the number of columns multiplied by the number of rows above the one you want, assuming you don't get confused and mess up. In contrast, in a markdown table, you navigate to the column you're curious about, then move down the column until you find the value you want. That's linear time!

When in doubt, choose the format that doesn't make it nigh impossible for some people to read. Because, you know, most people aren't using screen readers for fun; it's because they can't navigate the web visually.

3
  • 1
    There is generally no need for anything but the cell contents in a readable code format table. So this argument does not argue against ascii tables, only ascii tables with decoration.
    – philipxy
    Commented Jun 6, 2022 at 15:01
  • 18
    I disagree with the statement that this only applies to ascii tables with decoration. HTML tables can be navigated with keyboard shortcuts making it easy to read/re-read and understand the information within a table by quickly navigating up and down columns or across rows. It is significantly more difficult to navigate through an ascii table whether or not there is decoration.
    – Henry Ecker Mod
    Commented Jun 6, 2022 at 15:23
  • 13
    @philipxy ASCII tables without decorations are about as hard to read. They still lack all the navigation and features that a HTML table gives. Sometimes they're impossible because there is usually no difference between one space (ie a second word in the same column) and enough spaces to pad the rest of the cell (ie a second column).
    – Laurel
    Commented Jun 6, 2022 at 15:29
12

As a heavy answerer, I personally prefer the real tables.

The reasons for this are similar to user438383's; primarily, pd.read_clipboard (which internally utilizes pd.read_csv, for those interested) by default works very well with simple data (e.g. no spaces in cell values or column names), so the text-based table (usually copied from the output of printing a dataframe) is fine for that.

However, when the data involves any complexity, the real tables are more convenient as the cells and columns are tab-separated, so I can easily select the entire table, copy the text, paste it into an external text editor, replace the tabs with another character (e.g. |), and use pd.read_clipboard(sep='|').

2
  • 3
    Can't you use pd.read_clipboard(sep='\t') directly? Commented Jun 8, 2022 at 17:55
  • @mousetail It's odd, but no. The cells are fine, but the columns are messed up for whatever reason.
    – user17242583
    Commented Jun 8, 2022 at 18:41
11

As a Python and SQL user, I prefer tables as the code that I can copy and paste directly into my test script, plus the output of the print, SELECT * or similar statement, for visual understanding.

Python example:

df = pd.DataFrame(
    data =
    {'a': [1, 2, 2, 2],
     'b': [10, 20, 20, 21],
     'c': [100, 200, 200, 201]})
print(df)
#    a   b    c
# 0  1  10  100
# 1  2  20  200
# 2  2  20  200
# 3  2  21  201

SQL example:

CREATE TABLE test (name VARCHAR, age INT);
INSERT INTO test (name, age) VALUES ('Jack', 21), ('Jill', 20);
SELECT * FROM test; 
--  name | age 
-- ------+-----
--  Jack |  21
--  Jill |  20
-- (2 rows)
1
  • 5
    Ideally, this is the best way for debugging, definitely agree with it.
    – lemon
    Commented Jun 6, 2022 at 17:53
5

As an R user, I vastly prefer the SO formatted version as I can copy the table to clipboard and then exactly reproduce the data in my terminal with a single command - clipr::read_clip_tbl(). This isn’t possible with the first style and really is crucial for providing a necessary reproducible example. Therefore, it's a question of utility not style.

On the R tag, I would always accept an edit changing the former to the latter, as the former is really not that useful for anyone trying to answer the question. I can’t think of a single reason to have example data formatted like that.

5

Which you use, whether a markdown table or well formatted tabular text is, in my opinion, purely down to preference. Both serve the same purpose, and both are consumable by the end user. (For transparency, due to the tags I am active in I prefer tabular text, as I find them easier to convert to DDL and DML statements.)

If a user has taken the time to provide their data in a markdown table then leave it as it is, and likewise if it's well formatted tabular text leave it at that; simply changing the style is superfluous at best. Don't edit the post just to format the data to your preference.

If the data isn't well formatted (some users post data straight from Excel so it's tab delimited, but then looks awful as tabular text for example), then if when you improve the formatting you convert it to a markdown table, then I wouldn't be against this, as the initial data wasn't as easily consumable.


Assuming the question you reference is this, in truth it looks like that the OP wanted a markdown table, but then put the markdown in SQL code fences; so I would (personally) suggest that changing it so that the markdown table was rendered is fine, but the change should only be done if you were fixing other problems with the question. There is, in fact, not really anything that needs amending in that question by anyone other than the OP, so making the change was, at best, superfluous.

If you wanted, you could have educated the user instead to advise them that if they wanted the tables rendered as markdown tables, then they should remove the code fences (```) surrounding the markdown.

Ideally, however, for SQL questions DDL and DML is far more useful to users answering the questions.

2
  • "purely down to preference" - not quite. Check my answer for practical differences.
    – user17242583
    Commented Jun 7, 2022 at 17:13
  • 2
    @richardec your preference is that you can copy and paste it into pandas easily. Emphasis on preference.
    – Thom A
    Commented Jun 7, 2022 at 17:26
4

As you can tell by the answers here, which table format to use is very subjective and also depending on context.

Regarding official guidelines, have a look at When should I make edits to code? It's essentially the same thing as tables, from the editor's point of view.

TL;DR:
When editing posts, we should never make subjective changes based on personal preference/opinions, because we feel that one form is clearer than the other. For example one should never edit a post to change it to one's personal coding style preferences. Or to edit to change between British and American English etc.

Furthermore, edits which only make stylistic changes to a post are often considered too minor. Unless you fix some spelling/grammar/formatting/tags etc at the same time, you should probably not be making stylistic changes unless they significantly improve readability.

3
  • Thanks for your answer @Lundin, appreciated the use of references a lot. In the main referenced answer they say "Code in questions should only be edited for formatting and readability.". My specific case falls into the formatting more than the readability one, as I'm doing it for a more practical reason rather than a stylistic reason and, as I am assuming, not as a subjective edit, that's why I consider such edit not minor but relevant. Though I get your respectable point and I'd like to see the agreement of other users on your answer.
    – lemon
    Commented Jun 7, 2022 at 11:15
  • 1
    @lemon It might be a relevant edit in the right context, when some specific programming language or data format is being used. But not from a general point of view.
    – Lundin
    Commented Jun 7, 2022 at 11:18
  • Yes, I agree on that. @Lundin
    – lemon
    Commented Jun 7, 2022 at 11:19
0

When the table should be or would usefully be part of a Minimal Reproducible Example neither format is appropriate. The table should be given as initialization code formatted in a code block in columns so it can be cut & pasted & run & it should have been cut & pasted & run by the poster.

PS From my answer at New Feature: Table Support:

Unfortunately these new markdown tables are going to make it harder to get MREs because initial values will be given in a format that we can't cut and paste and run. In particular, for SQL, and, ironically, at Database Administrators.

8
  • 1
    Thanks for your answer @philipxy, I do appreciate that you're trying to clarify your own position in this meta post as I still can't understand your point inside the comments section of that post. In the Minimal Reproducible Example link there's no reference to tables formatting, why do you say that "the table should be given as initialization code formatted in a code block"? Could you provide more details with references in that regard?
    – lemon
    Commented Jun 6, 2022 at 14:24
  • 1
    If you cut & paste a query, does it run? If you cut & paste an ascii or SO/SE table into a tool that makes initialization code, is it the exact DDL the poster ran? (Both rhetorical.) From the MRE link: "Complete – Provide all parts someone else needs to reproduce your problem in the question itself".
    – philipxy
    Commented Jun 6, 2022 at 14:31
  • 3
    "If you cut & paste an ascii or SO/SE table into a tool that makes initialization code, is it the exact DDL the poster ran?", I'd like to hear the opinion of a moderator on this one. Theoretically you are right, in practice changing the format in the specific question does not impact the reproducibility of the problem. If you want to make 100% sure that you're correctly reproducing an OP's problem, then you need to force the OP to share a fiddle. I feel this argument more of a border-line extremism, maybe I'm right, probably I'm wrong, that's why I'd like to hear a moderator on this.
    – lemon
    Commented Jun 6, 2022 at 14:49
  • 1
    "you need to force the OP to share a fiddle" Again: "Complete – Provide all parts someone else needs to reproduce your problem in the question itself". (From another answer post on this question post: "Ideally, however, for SQL questions DDL and DML is far more useful to users answering the questions.")
    – philipxy
    Commented Jun 6, 2022 at 14:51
  • 2
    You'd probably close most of SO posts if we should strictly apply MRE, as it's extremely difficult to make a fully reproducible example by an OP, but also because a lot of questions come from new users. In the real facts, most questions get answered and the non-salvageable are plain avoided, which is not really the case of the post I edited.
    – lemon
    Commented Jun 6, 2022 at 15:43
  • Your comment is already contradicted by my answer & comments. I'm done.
    – philipxy
    Commented Jun 6, 2022 at 16:14
  • 2
    What do you mean by "The table should be given as initialization code"? Can you add an example (or a reference to one)? Commented Jun 6, 2022 at 21:33
  • 1
    Have to agree with this. I've very rarely come across situations where there was any benefit in having a table for data. Having to figure out how to convert a table back again into an actual data structure can be quite a hassle; in the worst case it will obscure that the "real" issue of a Q&A is actually in the data reading/parsing/format. Most of the time, it is better to provide a literal for the data that can be read directly and unambiguously by the language/tool. Commented Jun 7, 2022 at 11:24

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .