How to explain your code

Question

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
• 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?

Answer 1

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.

Answer 2

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.

Answer 3

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.

Answer 4

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.