19

What kind of Input and Output Code Styles are acceptable in SE?

These days I've heard about some comments (suggestions) about formatting. Some are my apparent error usages, and some are acceptable in my present point of view, but may receive criticism.

I am new in formatting, and I think new visitors would also confront formatting problems. I still remember my first several posts downvoted and closed.(So I feel happy when see some other's closed posts.) My philosophy is writing in Notebook and copy that to SE directly with good form. Also need work by hand but should as little as possible.

Let me say my confusion by examples.

1.About Input


This is the look in Notebook, with Input and Output tags.

In[22]:= sample1 = "[AA]AB[AA]BB[AA]B[AA]\
         CCCsssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssss";

I've seen someone's posts with such tags, and I that's not a good job to remove the tags to evaluate when one copied and pasted code into Notebook.

I'd like to use tags/signposts. Tags/Signposts are conceived to use in such cases.

How to combine Input[11] and Input[12] to get the result.

Multiple output results are pictures which do not follow the input but in the end of the post being a total image. This is one previous example. mathematica.stackexchange.com/a/26932/6648

style 1:

(*In[22]:=*) sample1 = "[AA]AB[AA]BB[AA]B[AA]\
CCCsssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssss";

style 2:

(*In[22]:=*) sample1 = "[AA]AB[AA]BB[AA]B[AA]\
             CCCsssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssss";

But I'd like this: The problem is if we should edit the second line of the code, should type 16 spaces, though I do it by program. So if acceptable, I'll use it.


style 3:

(*In[22]:=*)
sample1 = "[AA]AB[AA]BB[AA]B[AA]\
CCCsssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssss";

Problem with style 2, new lines should only type 4 spaces as much as the first line. But maybe it is not with a good look of (*In[22]:=*) in one separate line.

style 4:

(*Input ==> 1*) sample1 = "[AA]AB[AA]BB[AA]B[AA]\
                CCCsssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssss";

style 5:

(*Input ==< 1*) sample1 = "[AA]AB[AA]BB[AA]B[AA]\
                CCCsssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssss";

style 6:

(==========================================================================>Input 1*)

sample1 = "[AA]AB[AA]BB[AA]B[AA]\
           CCCsssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssss";

2. About output

Some are same to that about input. There is some problems/confusions with the usage of blockquotes. The appearance in meta are not the same to that of main site(I like yellow background).

with (* *) we can copy directly the two input codes (with outputs between them) into Notebook, maybe with blockquotes, we can also use one code extractor to import to Notebook too.

But rm-rf seems disagree with the usage of blockquotes in output. And I see Mr.Wizard and someone else do not use the (* *) in output, but just use blockquotes with codeblock for output.


style 1:

(*Output==> 1 "[AA]AB[AA]BB[AA]B[AA]\
CCCsssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssss";*)

style 2:

(*Output==> 1*) "[AA]AB[AA]BB[AA]B[AA]\
                CCCsssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssss";

style 3:

(*"[AA]AB[AA]BB[AA]B[AA]\
                CCCsssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssss"*);

style 4:

(*"[AA]AB[AA]BB[AA]B[AA]\
  CCCsssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssss"*);

style 5:

(*
  "[AA]AB[AA]BB[AA]B[AA]\
  CCCsssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssss"
 *);

style 6:

(*
 Output==>
 "[AA]AB[AA]BB[AA]B[AA]\
 CCCsssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssss"
*);

I'll edit if necessary to add more kinds of styles and questions.


Links of my posts with some problems. Some are hidden in the revision history. Sometimes when I use one seems acceptable formatting, and still will be edited by others with another formatting, then I doubted my older usage of some acceptable formatting(not those obvious errors.)

Replace with position and order number

StringReplace except some pattern

https://mathematica.stackexchange.com/questions/27080/how-to-look-up-the-dictionary-for-some-bad-form-phrase

https://mathematica.stackexchange.com/a/26932/6648

https://mathematica.stackexchange.com/a/27084/6648

https://mathematica.stackexchange.com/a/26975/6648

Little problem with Through

  • Over the course of 1.5 yrs, there are two styles that most users have converged on — Code in InputForm without any cell labels commented or not (we don't care if you're now at In[973]) and output commented out, to allow for easy copying. Some add an additional quote block if it's important to highlight it, but ignore it otherwise. You might find occasional differences here and there, but that is not a reason to try and use every arcane style in your posts one-by-one to see what sticks. If you haven't noticed already, there have been a few unhappy grumblings re: your style experiments... – rm -rf Jun 19 '13 at 5:07
  • 1
    @rm-rf yes, I noticed some grumblings, so I'm here to ask this question... experiments are needed in learning, otherwise someone else maybe would do some similar things. I'm making progress in formatting. – HyperGroups Jun 19 '13 at 7:00
  • I think output is best left as 4-space-indented code block. It looks closest to the original, and I don't think people copy the output as often as the input - if they do, it might be to form new input anyway (eg output from Table). – cormullion Jun 19 '13 at 9:27
  • rm -rf has essentially said it all below. The only thing I would add is that I always break up lines that cause side-scrolling, and I personally prefer quoted output (but rm -rf makes a good argument for using comment style output). – m_goldberg Jun 19 '13 at 10:30
  • Releated: meta.mathematica.stackexchange.com/q/338/121 – Mr.Wizard Jun 19 '13 at 11:33
  • 1
    Possible duplicate: meta.mathematica.stackexchange.com/q/2/121 – Mr.Wizard Jun 19 '13 at 11:34
  • @Mr.Wizard fine, I've read some of that linked posts, and learned some fromt that. – HyperGroups Jun 19 '13 at 13:33
32

The problem with presenting a set of styles and asking someone to choose one, is that the choice depends on the personal tastes of each user and I'm loathe to suggest that there is only one right way to follow. However, we, as a community, have identified certain preferable characteristics in code blocks (I don't have references for these, but it's based on observations from my time spent on the site, seeing comments from users and what gets adopted, etc.):

  1. One should be able to copy-paste-evaluate the code block in Mathematica. This means that In[..] labels or Input Code ==> and similar constructs are not allowed.

  2. The code block should be as noise free as possible.

    • Wrapping useless fluff in comments, like (* In[..] := *) etc., only adds to the visual noise, even though it can be copy-paste-evaluated per point 1. Honestly, no one cares if your current kernel session is at In[973].

    • Using Greek/fancy characters excessively, which copy as \[Alpha], for instance, is also not a good practice. Do not write \[Tau]\[Epsilon]\[Mu]\[Pi] when you might as well call it temp.

    • Sometimes, Greek letters are necessary when the variable refers to notation in a paper/formula or is conventional for the quantity it represents (e.g. μ for mean, σ for standard deviation, etc.). In such cases, try to replace it with the actual Greek letter, i.e. \[Alpha] becomes α instead of leaving it as such. There is no known automated way to do this from the Mathematica notebook, although some hacks and workarounds exist for some OSes.

  3. Do not use fancy typesetting in your code. This is something that new users tend to do, because it is quite "fascinating" to use a system that lets you define a variable as a11 instead of a11, sum a series with , etc. However, such typesetting can often be the source of several errors, because a11 is not actually a symbol like a11 is, not to mention the fact that it copies as Subscript[a, 11], making the code bulky and unreadable. Likewise, don't litter the code block with "\*StyleBox[\(... such as from copy-pasting formatted strings. Remove all such unnecessary details (unless the question is explicitly about that).

  4. Try to use sane and reasonable indenting/formatting. There is no preferred/documented/official way to indent/split Mathematica code but some reasonable guidelines can be proposed, which hold good for most programming languages (e.g. be consistent in your use of spaces vs. tabs, be consistent in the tab width i.e., don't indent one line by 4 spaces, the next by 7 and then 3, etc.).

    Also, try to avoid the code block scrolling sideways. Break lines a little early, if necessary, to make it fit (2 readable lines is better than 1 long line that needs scrolling). If the only part that extends out is a terminating ; or something similar, then I guess that might be fine. I've also seen users post lengthy sample data (lists/matrices/strings) on a single line, so as to reduce the space they occupy in the post. This seems like a good idea for sample data for which the structure of the input data is not important.

  5. Keep the code and variables minimal and simple. While this is only tangentially a "style", I feel it deserves to be mentioned, because most new users don't understand this. It's not necessary to have very long meaningless (to us) variable names if you're only going to use it once. Often times, a lot of the regular users can spot mistakes in code simply by reading it and visual noise from 2-4 and lack of simple names/code can only make this harder for all involved.

As for output cells, there are two main styles that are used:

  • (* Comment out the output *), which I believe was put forth by Sjoerd (a long time ago). The advantage to this is that the code block can be easily copy-pasted in one go without having to worry about evaluation errors.

  • Quote the output,

    sometimes inside code cells
    

    This was suggested by Mr. Wizard, and it serves to visually distinguish the output from the input.

You'll find both styles in use, but personally, I strongly dislike the second one because

  • it is an orgy of colors that don't go well — syntax colored text on gray background on yellow back-background!!
  • It splits a single code block into several code blocks (because there's a break to include a quote block), which makes it harder to copy paste (more work). You might also accidentally copy the output because the syntax highlighting made it look like input code.
  • It is an abuse of the quote style, and reduces its importance in actual uses (I now tend to skip quoted text because I assume that someone has again abused it to highlight output text)

Critics of the first style counter that it is too subdued and one might accidentally overlook it. There was a proposal for a specific "output style" to avoid such confusion, but nothing came of it. In the end, the above objections are my personal opinions and I'm not enforcing it on anyone. However, if your post is formatted crappily, I'll edit it and rework it the way I usually do it. Folks have been pretty good here about not stepping on each others styles even if we disagree about its usage.

  • 4
    Good answer, saves me having to write anything! Might be worth mentioning that code shouldn't have to sideways-scroll... – cormullion Jun 19 '13 at 9:22
  • ok, avoid using \[Tau]\[Epsilon]\[Mu]\[Pi] seems hard to me, by now, because Copy as Input just come out these. I should learn that. – HyperGroups Jun 19 '13 at 13:41
  • 1
    @HyperGroups the "simplest" way to get greek characters is to invoke the TeX extensions, and copy the greek letters from the preview, if you don't have os support (or haven't bothered to turn it on). Otherwise, attempt to use the long-hand equivalents. – rcollyer Jun 19 '13 at 13:52
  • 4
    Maybe we should put some common formatting rules in FAQ and put a summary in About with link to it. And in fact I do agree you that a gray block in a yellow (Lighter[Orange, .9]?) block looks just NOT good... We really should have an "output style". – Silvia Jun 20 '13 at 6:10
  • @cormullion there's a lot of sideways-scroll hate here (m_goldberg and rm-rf chimed in on the topic as well). Might there be valid reasons to preserve side scrolling, say for instance, if a question requires that a variable {{x1,y1}, .. {x100,y100}} to be defined explicitly? (Or do we simply complain that such a question isn't sufficiently chopped down by the questioner?) – bobthechemist Jun 21 '13 at 12:04
  • @bobthechemist ah he's added that in second paragraph of point 4. If we're not expected to read the data, this sounds like a good idea! – cormullion Jun 21 '13 at 12:08
  • @cormullion true enough, and I had even read through that section (thoroughly, I thought). Should be a rule against commenting before the first cup of coffee... – bobthechemist Jun 21 '13 at 12:13
  • 1
    I really enjoyed reading this. It summarizes quite everything about these things which simply emerged over the time M.SE is existing. Very nice. – halirutan Jun 28 '13 at 19:59
  • I noticed your a<sub>11</sub> code doesn't format correctly (anymore?) Might be related to the new CSS. – Sjoerd C. de Vries Mar 15 '15 at 8:20
  • It looks fine for me in Chrome and Safari @SjoerdC.deVries – rm -rf Mar 15 '15 at 14:43
  • I just see a11 on my iPad's Safari. – Sjoerd C. de Vries Mar 15 '15 at 17:09
  • OK, not so on my windows laptop. Apparently a quirk of iOS. – Sjoerd C. de Vries Mar 15 '15 at 18:46
  • Sometimes I find it useful to bring together several outputs as seeing them more closely juxtaposed can make it easer to absorb - with the corresponding implementation helpers – Ronald Monson Jul 22 '15 at 8:08

You must log in to answer this question.

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