Since I am now programming in a very esoteric language, Pyth, I like to include in my posts an explanation of what my program is doing. However, I seen many different explanation formats, and I'd like to know which one(s) people prefer. Some options I've seen:

• In line comments with indentation to show what operates on what
• Paragraph form explanation
• Equivalent of the program in a more self-documenting programming language.

Which do you think is/are best?

• like this Jul 2 '14 at 17:32
• @m.buettner I like it! Jul 2 '14 at 17:43
• @isaacg Since you created Pyth, could you point me to a page with Pyth examples of syntax? I'm trying here: pyth.herokuapp.com and I cannot for the life of me figure out the lambda syntax, or how to use range with the step argument, or alternatively use the step arg of the slice operation. Feb 24 '15 at 17:54

I've recently been experimenting with different ways of doing this. My goals going into it were keeping the height of the answer low (previous attempts have gotten long) and explaining what exactly the code does instead of why it does it. This is antithetical to what usually makes for a good way to explain a program, but in my opinion it's more fun to read on sites like this because you get riddles like "Why did they do this here?", answered later in the program with "Oh, it lets them a neat trick to save characters here!". Those moments are my favourite thing about reading this site. A thorough, literal explanation of what the code is doing allows people who aren't familiar with the language to play along.

I recently figured out a way to explain my code and meet those goals. As an example, a recent question asked for a program or function to list every letter of the alphabet ordered by how often they show up in an input string. This was my answer:

f=lambda s:''.join(sorted(map(chr,range(65,91)),key=s.upper().count))[::-1]


And this was my explanation:

                                  range(65,91)                              # The numbers 65 to 90
map(chr,range(65,91))                             # Convert to ASCII

s                       # The input string
s.upper()               # Convert to uppercase
s.upper().count         # Function literal for 'how many times the argument appears in the string'

sorted(map(chr,range(65,91)),key=s.upper().count)        # Sort by that function
''.join(sorted(map(chr,range(65,91)),key=s.upper().count))       # Concatenate to string
''.join(sorted(map(chr,range(65,91)),key=s.upper().count))[::-1] # Step through by -1 (i.e. reverse string)

lambda s:''.join(sorted(map(chr,range(65,91)),key=s.upper().count))[::-1] # Make it a function (return is implicit for lambdas)
f=lambda s:''.join(sorted(map(chr,range(65,91)),key=s.upper().count))[::-1] # Give it a name


I like this for a couple reasons:

• Simple enough to read along with if you don't know python (I think, at least. I know python so I'm not a good judge of this)
• Shows you where to start reading, which isn't always obvious in golfed code (and if there are multiple unrelated parts of the code that have to come together later, like in this answer, you can define a different entry point for each bit)
• I think it looks nice

Of course, there is one big con:

• Horizontal scrollbars make the baby Jesus cry

Overall, though, I think I'll stick with this until I find something better.

• +1 for simplicity, -1 for making baby Jesus cry Jul 3 '14 at 16:55
• I really like this system if the horizontal scroll bars can be avoided, so I think it's perfect for my language in particular. Thanks! Jul 3 '14 at 17:57
• I gave this a try yesterday, and while I really like it I found another con: editing the explanation when you make a change to your program is incredibly tedious. Like, wow. So I guess you should wait with adding such an explanation until you're really sure you're done golfing. Alternatively, what we need is a code-annotation tool which can render these beauties. :D Jul 4 '14 at 13:03
• I made a quick JSFiddle that lets you make these without copy-pasting and hitting spacebar lots. Jul 14 '14 at 12:46

That depends on the format of your language, and on your taste. Inline comments are only going to work if your language actually supports such a thing, for example. I wouldn't bother trying to rewrite the same code in a different language, though.

• The only reason I mention the last one is because it is particularly easy in my language. I agree that it is impractical in general. Jul 1 '14 at 19:01
• @isaacg The last one is also what I do in PYG Jul 1 '14 at 19:09
• @isaacg I liked your explanation in the max sequence golf. Jul 2 '14 at 9:51
• It depends on the program too. Sometimes the trickiness is in the syntax abuse; other times it's in the algorithm. The two fit with different styles of explanation. Jul 7 '14 at 10:45

As a J golfer, I've used all of the above explanation types, and more, for some of my answers (e.g. 1 2 3).

My process for choosing which explanation to use is based on what kind of golf it is. If it's something small and won't make horizontal scrollbars, I'll do an "explanation-by-explosion" (my name for the thing in undergroundmonorail's answer) and add comments to the right. If it's something very linear, I'll do a paragraphs thing. It's really dependent on what kind of golf you've written and how much you can break down your language.

The important point I want to make, though, is that it's okay to fudge some facts for explanation simplicity. Sometimes it's better to gloss over exactly how something is accomplished, or to imply that a technically incorrect but easier-to-explain behaviour is occurring.

For instance, in J explanations, I will treat the atoms ] and [ as variables referencing the left and right arguments to a verb, when actually, ] and [ are verbs that have to fit into a rigid syntactic structure that at first sounds very arbitrary until you know enough J to understand why. It's an important distinction to a golfer, but explaining it to someone that doesn't care to learn your language would be wasted breath.

My point is that non-Jers looking at J explanations would rather see which parts of the code correspond to what parts of the algorithm (in my experience). Obviously, J is very different from the many other languages out there that require explaining, but the principle is the same: people will look at the documentation if they want a full account of the relevant syntax; here, they just want to see your algorithm.

• +1 for choosing the most appropriate format depending on what suits the answer best. Especially in light of that, it might be nice to collect a CW list of different explanation formats with pros and cons on meta, so interested users can browse through it to see some new explanation styles and choose one that is most appropriate for the current challenge. This very question here might serve, but now it's already a bit cluttered with general "I do whatever is appropriate answers". Jul 6 '14 at 10:02
• codegolf.stackexchange.com/a/33084/18638 is also a possibility, especially if better commented (also: I'm scripting something to convert Visio documents to J functions.) Jul 8 '14 at 21:56

I have a tendency to be quite wordy in my explanations, though i can be a bit more brief. The wordier I am, the more pleased (smug?) I feel about my answer I think.

In all cases I prefer the paragraph format over line comments.