2

I am torn between two worlds on this one. When answering a question, I like to post clean, minimal code. However, sometimes that code may not be entirely clear to the original asker and it can be difficult to explain each line within the body of the answer itself.

Therefore, I will often place comments throughout the code in my answer, explaining what the code does and why we do it that way. This, obviously, can lead to some longer answers and may be more confusing due to all the extra text.

So, is there a standard in place here for this? Should our code be completely void of comments and just demonstrate the concepts and procedures involved? Or can the code itself be a part of the answer with the comments within it?

My answer on this question may help illustrate the situation. I worried that my initial, code-only, approach may not have been clear for someone that is new to coding so I repeated the code later with the additional comments.

Note: I am not suggesting our answer should consist of ONLY code with comments (such as this question), but just whether it is bad form to post answers with more information within the code. I do still believe some explanation should be given outside code as well.

2
  • When you need to, yes. If you don't need to, no. That's also the schedule you should follow when cleaning your belly button of lint.
    – user1228
    Commented Jun 28, 2018 at 20:42
  • 1
    I'm not sure why this question is downvoted. It's not a feature request, nor is it trying to propagate a practice, it's asking for advice.
    – jpp
    Commented Jun 29, 2018 at 9:27

1 Answer 1

7

The answer is seldom the code. That is to say, if you put more emphasis on the code than you do the actual solution, then it really doesn't matter how many comments you add to the code; you're not really divulging the information in an easier-to-digest format.

Thing is, anyone can write code which compiles and accomplishes a Thing™. Not everyone can explain the overarching goal and how they're going to get to it.

In the context of your(?) answer, it would be far more valuable to clearly elaborate what you're trying to accomplish without the use of code. Once you've got that explanation, then you can use code to illustrate what you just explained with an example.

As far as a standard, there isn't any - people often post "Try this" with a few dozen lines of code and sometimes those answers are okay, others they're reviled. My recommendation to you would be to adhere to a better methodology of explaining what the heck it is you're actually doing, which would mean getting away from leaning on code as the explanation.

1
  • 1
    I absolutely agree! I learn much better when I'm explained the "Why" not just the "How." That's always been my goal when posting an answer.
    – Zephyr
    Commented Jun 28, 2018 at 5:49

You must log in to answer this question.

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