-51

What people usually do is to to write explanations of their problem outside of code blocks, but it would be shorter and clearer to write the problem settings as comments in the code block. Here are the perks:

  • It's shorter. The eyes of the viewer don't have to make long moves. One can view the whole problem on one page, no need to scroll back and forth.
  • It's easier to copy the whole code at once when there's only one code block. And a code should be self-explanatory if the desired output is provided.

I do not intend to impose a site policy, just to discuss whether people agree that this method of adding information is beneficial and would be good advice.

enter image description here

20
  • 3
    "What peole usually do is to to write explanations of their problem outside of code blocks" [citation needed] that breaking up a logical unit of code into multiple chunks with comments in between each is a common practice. Yes, it happens but I don't think it's common enough to require some sort of site policy.
    – VLAZ
    Jul 14, 2022 at 12:30
  • 2
    Also, your example does not provide one cohesive unit of code. The first two blocks can probably be merged. But the last one does not belong with them.
    – VLAZ
    Jul 14, 2022 at 12:32
  • It's not "should (be included)",... yes, Code should contain some Comments for understanding its Logic/Workflow, but you still need some "Explanation" about the part answering the specific Question/Issue of the Asker...
    – chivracq
    Jul 14, 2022 at 12:33
  • 8
    Shorter isn't necessarily better. There is a reason many languages have coding styles that promote adding vertical and horizontal whitespace: stretching things out makes it easier to digest the individual pieces. It is pretty telling that even your example uses technically superfluous whitespace. Jul 14, 2022 at 12:40
  • 4
    I still don't get what is being discussed here. So far you've expressed you prefer that. Which is great but...so what? It's also apparently not about a site policy, which means that the discussion has no impact on how the main site is to be used. So, what is there to discuss?
    – VLAZ
    Jul 14, 2022 at 12:44
  • I don't know why this post was downvoted so much (-15). But now I know that most people don't agree on me on this one but I'll continue to post like in the right image
    – Julien
    Jul 14, 2022 at 13:03
  • Or askers could include both, explanations outside and inside code
    – Julien
    Jul 14, 2022 at 13:08
  • 4
    Why would duplicating explanations outside and inside the code be better?
    – Wai Ha Lee
    Jul 14, 2022 at 13:22
  • @WaiHaLee Because I prefer to read directly the code part, I usually skip the explanations
    – Julien
    Jul 14, 2022 at 13:24
  • 7
    Not intending to be snarky, but it's rather telling that this meta question lacks explanations. Instead of forcing your content to fit into comments, you might want to explore how to use proper text to convey information. Jul 14, 2022 at 13:31
  • 18
    "But now I know that most people don't agree on me on this one but I'll continue to post like in the right image" - so you know that despite it not being your personal preference, most people who've expressed an opinion believe the first option to be clearer... but you'll continue to post with the second option. I don't understand why you wouldn't modify your behaviour to try to make your posts as clear as possible to other people. (It's like naming conventions: you may have your own naming conventions in your project, but on SO it makes sense to use standard ones.)
    – Jon Skeet
    Jul 14, 2022 at 13:41
  • 2
    Plus, it's easier to coy the whole code at once when there's only one code block > nothing prevent you to have explanations and the corresponding code blocks/lines in the question description and then end the question with a bigger code block giving the [mre]. Jul 14, 2022 at 13:49
  • 2
    @Julien I hope by "duplicate" you mean "move".
    – Gimby
    Jul 14, 2022 at 14:07
  • 1
  • 2
    there are code comments, complementing the code (or text that should be comment) AND there are explanations for the question (or there should be such explanation) -- I agree that first one should be part of the code, BUT the second one must not be part of the code (and must be present - post without explanation is not a question) Jul 15, 2022 at 6:55

6 Answers 6

29

Only code comments belong in the code block. The explanation of your code should be provided regardless of any code comments. They're not the same thing.

25

Do you agree that questions/answers on Stack Overflow should be included in code blocks as comments instead of long explanations?

No.


It's harder to delineate between comments in the code and comments added for the question, e.g. where in the following code is the question?

if ( File.Exists(getSerialisationPath()) )
{
   // Load the entries from the path
   _entries = deserialise();
   Logger.LogMessage($"Deserialised {_entries.Count} entries from {getSerialisationPath()}");
}
else
{
   // No entries to load - just create a new instance
   _entries = new();
   Logger.LogMessage($"No data found to deserialise");
}

try
{
   // What alternatives to the try/catch could I use here?
   // 'method' may throw - as it's not our code, put it in a try/catch
   method(1, "Hello");
}
catch ( Exception ex )
{
   // Handle the exception here (elided)
}

Now, how about this?

if ( File.Exists(getSerialisationPath()) )
{
   // Load the entries from the path
   _entries = deserialise();
   Logger.LogMessage($"Deserialised {_entries.Count} entries from {getSerialisationPath()}");
}
else
{
   // No entries to load - just create a new instance
   _entries = new();
   Logger.LogMessage($"No data found to deserialise");
}

What alternatives to the try/catch could I use here?

try
{
   // 'method' may throw - as it's not our code, put it in a try/catch
   method(1, "Hello");
}
catch ( Exception ex )
{
   // Handle the exception here (elided)
}
8
  • One could put the questions in CAPITAL LETTERS as comments to make them stand out
    – Julien
    Jul 14, 2022 at 12:31
  • 18
    @Julien Yet another horrible idea, considering what such capitalization conveys.
    – E_net4
    Jul 14, 2022 at 12:33
  • 13
    @Julien ALL CAPS is generally seen as shouting. Capitalisation exists for a reason and not using it makes text harder to read. So, posing questions in ALL CAPS will appear pretty rude to many people. Jul 14, 2022 at 12:34
  • Or add characters such as !!! or anything not alphanumerical
    – Julien
    Jul 14, 2022 at 12:34
  • 19
    @Julien if your proposed clarification requires additional formatting to make it clear what it is, then I'd argue, it's not improving the clarity.
    – VLAZ
    Jul 14, 2022 at 12:35
  • It's more concise
    – Julien
    Jul 14, 2022 at 12:35
  • 2
    @Julien concise plus ungood clarity.
    – VLAZ
    Jul 14, 2022 at 12:36
  • 15
    @Julien Just because something can be more concise doesn't mean it should be. I can compress a thousand lines of code into one, doesn't mean it's easier for a human to understand. You're already going to be scrolling on the SO and the rest of the internet, there's a reason it was invented and why some apps make it a central mechanism, being able to pick out the important information while scrolling through the information is vastly more important than having to scroll less.
    – vandench
    Jul 14, 2022 at 12:45
25

No. Code comments are not meant for general prose and they are not suitable for it either.


The point of a code comment is to describe the immediate code around it. Including a general question such as "And for dataframes?" is not actually about any code. It is a meta commentary on the situation established by the code, not about the code itself. By using code comments for both purposes, it becomes unnecessarily difficult to disentangle the two.

The point of markdown is to allow diverse formatting: style, links, quotes, lists, images and more. In most programming languages, code comments have no such capabilities and are inferior to express content that would benefit from it.

15

I think there's two separate issues here:

Keeping code blocks that must be copied to test a solution all in one piece

This is a good goal. The "slicing with row index by..." comment is exactly the sort of comment that should be a code comment, because it's describing the code it's adjacent to. This is made worse by extracting it from the code, as though these are separately labeled code blocks rather than the preamble to your actual question.

Making the actual question obvious

The question that you're asking should not be in a code comment. For all I know, that comment is in your actual code that you wrote, and your question for Stack Overflow is something else. Separating it makes it clear that your question is not code.

8

Conserving vertical whitespace isn't a realistic problem for well posed questions

  1. If you need to mention single lines of code in the middle of the prose of a question, that is supported:

Suppose I have a vector vect = c(1, 5, 4). I know that I can slice it using slicing syntax - vect[2] - but can I do it with a function instead?

If the MRE is that simple, then there is no reason to bother setting up a full code block. Notice how I am able to ask the question clearly and show the relevant code, in much less space. (I did not include the bit about dataframes, because making that actually make sense as part of the same question would require a complete rewrite.)

  1. If you feel the need to break up a block of code repeatedly in order to ask something, then you probably have multiple questions. Such an attempt should be closed as "Needs More Focus".

  2. If you're breaking it up to explain why each block of code is relevant to the example - is every block relevant? Use a code comment if those blocks are consecutive in the code and part of a coherent MRE. If you need to describe a situation where, for example, the code is split across multiple files, then definitely don't jam them together with filenames in code comments. That's misleading and easy to overlook. Plus you will probably need to explain the purpose of the separate files, and why the MRE requires such a split.

  3. Similarly, don't use the same block of code to show multiple alternatives or attempts. It is useful to have that separation and page styling, so that people trying to reproduce your example can immediately see where to start and stop the copy-paste of your code.

  4. "Shorter" and "clearer" can be in conflict. From the example, "And for dataframes?" is hard to parse. The comments simply saying # [1] 5 require a lot of interpretation. Code is for explanatory purposes. On Stack Overflow, we ask questions about code. The important thing is the code, but we still ask questions - in English.

2
  • For me that's the opposite : if the question is simple, code alone should be enough ?
    – Julien
    Jul 14, 2022 at 19:28
  • For a programmer used to the programming language I used (R here), code would be easier to read than English text
    – Julien
    Jul 14, 2022 at 19:29
7

A lot has been said in this meta post. I have but one thing to add which is kind of a running theme of this meta post.

Do not go against the grain.

Our personal opinions do not matter when it comes to how we, as visitors, operate on this site; we need to be team players and do it by the books. That includes opening up the mind to the idea of doing things differently than what we personally prefer. If there is one thing Stack Overflow does not need it is people who treat the site as if it is their property. We share this treasure trove and should thus act accordingly.


However, there are always two sides to a coin. I think this meta post is actually casting the net far too wide and is therefore an X/Y problem that is causing confusion through noise and miscommunication. What you are after is if specifically, R programmers dealing with R questions prefer it. That would have potentially been a whole different discussion because R simply is very different from regular programming languages and thus the way programmers think and operate will probably also be different.

But if true, that is a mistake that hooks back into treating the site as your own property, sort of. As an R programmer, you should not assume everything is R, there is a whole world of programming languages and tools out there and it occupies 99.9% of Stack Overflow. A percentage I pulled out of thin air, "most of Stack Overflow is not R". So next time... be a little more specific about it.

0

You must log in to answer this question.

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