2

Is there a preferred style on this site, where to put explanations of the code one posted?

Should it be done like this:

Some explanation above

if (x != y)
    //do something

or like this:

if (x != y)
    //do something

some explanation below

Or is this completely irrelevant?

5
  • 11
    Either is acceptable but in my opinion, it's better to state the issue in words first and then demonstrate it.
    – Paulie_D
    Sep 9, 2018 at 10:16
  • @Paulie_D yes, plus it helps to understand the code which, if it's on SO, is quite likely to be badly-formatted with single-letter identifiers. Getting some understading of what it's supposed to do, and how, reduces the chance that I will just downvote it, close as 'unclear' and move on. Sep 9, 2018 at 15:38
  • I quite often introduce the code fragment with words such as 'You currently have code like this' followed by the code from the question, and then the explanation. This protects the answer from edits to the question making the answer seem inaccurate/irrelevant. The answer may now be irrelevant because the question changed, but at least the answer is self-consistent with some version of the question and latecomers can see at least that the answer was at one time relevant (I hope). Sometimes the preamble will include a brief outline of the issue, and the postamble then amplifies the details. Sep 9, 2018 at 20:46
  • 1
    Imposing a coding style on every single user that visits Stack Overflow is even more of a pipe dream than getting everyone on your individual project to adopt a coding style.
    – zero298
    Sep 10, 2018 at 14:28
  • Is this question salvageable by an edit, or should I leave it like this?
    – some_user
    Sep 10, 2018 at 18:42

1 Answer 1

10

If you have a programming problem and you want a colleague or friend sitting next to you to help you, what would you do? You would ... browse through the code and simultaneously tell what's going on. This isn't very well supported by the Stack Exchange post format; I'd rather copy entire files from an MCVE than having to weed out explanations every 4 lines of code. (Of course, good comments in the code can be helpful too.)

So I'd rather follow the practice used by most coding books; generally, they will tell what a piece of code should do above the code itself, and optionally put some notes below the code discussing the finer points.

But I think the most important part is not the placing of the explanation, but the fact that it's clear, unambiguous, and not formatted as code.

3
  • 1
    Thanks, I just used this to make more visible where the examples begin and end. Normally, I don't use it when explaining code.
    – some_user
    Sep 9, 2018 at 10:58
  • Great, keep it up! It's just one of my pet peeves and it's IMO always worth repeating.
    – Glorfindel
    Sep 9, 2018 at 10:59
  • 1
    I addressed that with an edit to the question.
    – BoltClock
    Sep 9, 2018 at 16:13

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