-5

I have come to believe that this should be a new question, but it has spawned from answers and comments I have written with regards to these two Meta Stack Overflow posts: Code in comments should be Multi-line comments on Stack Overflow.

What follows is my argument for a feature that is sneakily importantly needed: proper multilining in comments (at least for code) and so long as that code follows legibility constraints that are expanded versions of those suggested for representing code in comments in Code in comments. In that discussion, there seems to be too much focus on a single use-case of code in comments that is overemphasized at the cost of seeing the other kinds of code that are not well represented by the example poorly formatted when it is inevitably written into comments.

Currently there is no system for properly formatting code left in comments. I have to point out that if the consensus is that code in comments is ever useful, even if the goal is to dissuade people from posting long chunks of code into comments, wouldn't it be desirable to have proper line-breaks and other simple formatting options (optional syntax highlighting) for code snippets that are not too many lines long.

New python executables in MYENV/bin/python3.4 
Also creating executable in MYENV/bin/python 
Installing setuptools, pip, wheel...done.

is much easier to read than `> New python executables in MYENV/bin/python3.4 > Also creating executable in MYENV/bin/python > Installing setuptools, pip, wheel...done.`

And I'd much have preferred to write that (here: What is the easiest way to remove all packages installed by pip?). And it would not have taken up much more space compared to other comments. So legibility suggests that better formatting for those shorter code snippets should be desirable if it is recognized that code snippets should be subject to any strictures of design.

Furthermore — that concern – I'd argue – should win over a theoretical concern raised in this cross-linked post which shifted a discussion about multi-line comments to the appropriateness of including code in comments in the particular case where you are writing modifications of example code from the post and this produces a synchronization attention-death. However, this use case does not cover all the kinds of instances where code formatting would be useful. Nor does it eliminate the number of people who have discussed the need for line breaks at least on critiques of answers and others who care enough to have extensively tried to test for this ability (notable for amusing persistence is @Kieran in a comment thread in this post).

In the words of @aximili:

+1 to VitalyB. Line breaks are important

From the perspective of this question's implied point of not wanting to encourage long comments filled with illegible long strings of code (such as >200 characters of consecutive code), even if you have multiple lines of code that skew the display of the comment section to a more vertical dimension, you could put an upper limit on numbers of lines allowed , and if the warning is instituted in the form as it is described here, it could additionally warn people if they exceed some threshold of character density or lack of density. Either cramming a lot of code onto the line (e.g., with multiple semi-colons separating code snippets) or too little code per line (just 100 line breaks in a code block) would be worrisome practices that should be discouraged with such a warning if not an outright error.

So in that sense, it seems like this warning about long code in comments is worthwhile, however, for the things that don't trigger the warning, there should be a better method for formatting them. Currently they are far too hard to read. Scaling Consolas down to 11 pxs (14 pixels leading) might make it a little hard to read if viewed at a distance, but 12 pxs (15 pixels leading) is still a bump down and would still have less leading if there is an analogous concern to font shrinking observable in comparing the main text to code in questions and answers.

But more generally the critiques that have been raised in various places (1, 2, and 3, by @Asad) do not seem to hold for all cases of giving code snippets. In some cases, the code may be given as an example of alternative output or other results that may occur.

Worse, in whitespace sensitive languages like Python, this kind of whitespace dissolution can actually transform code from valid to invalid. To not do this is in effect making it impossible to provide even short snippets of some conventionally, validly formatted text that would otherwise meet the criterion of being a readable comment.


Supplementary note on text formatting specifics and their relation to minimal max-lengths for code snippets in comments:

For reference the main text is Helvetica Neue Regular (15 pixels with 19 pixels leading) and code blocks are typeset in Consolas (13 pixels with 16 pixels leading), since in the comparative context in a comment, the main text is Helvetica Neue Regular (13 pixels with 16 pixels leading).

The minimal max for multiline code would need at least a total of 5 lines would make it no longer than the max of the current comments with single spaced 600 characters per code line, even at the same Consolas (13 pt with 16 pt leading) it uses for inline code formatting in questions, answers or comments.

I can go on, but I don't know if there are arguments that exist that would satisfy someone that did not find the above to be at least somewhat convincing. Even if counterarguments can be made against any one of the individual points, it will be hard to find a single counterargument that fits with what was previously recorded as I have linked here. If there is another argument please respond, I'm interested to hear it.

Some of this was built off of this answer to one of the aforementioned links.

Edit: This also gives a potential solution to this problem: Convert code blocks to backtick syntax when converting answers to comments at least in the cases where the codeblock is not too large.

9

No. Comments are comments, not entire code blocks. We have answers for that. Comments are meant to be short-living parts of information traveling between users on an active question or answer.

Comments shouldn't contain entire blocks of code. If you have something to add, do (a suggestion for) an edit. If something doesn't work, you don't need the entire code snippet, just point out where it goes wrong. If it is an addition to the question: edit it in.

If you want to comment with a code block, I think you are missing the point of comments. I have never felt the urge to comment with a code block, and I have been around for quite some time already.

  • How do you handle this when your comment is critiquing the answer which may require formatted text to describe the problem? This is especially relevant if sharing an error from someone's code, which would not necessarily be an appropriate edit to their code block as it is an edge case not relevant as an answer per se (e.g., it may only occur on some operating systems). This is but one example where your point about "not code blocks" would involve both including code & prose. In fact I would be on board for banning comments that are only code blocks, but I figured that was a different issue. – mpacer Aug 4 '15 at 9:31
  • Well, your link some line of code doesn't work. It conflicts with the part where you do some frobbing. The a should actually be a b. – Patrick Hofman Aug 4 '15 at 9:32
  • @mpacer something like that? – Patrick Hofman Aug 4 '15 at 9:32
  • What if that some line of code was multiple lines long? Or if you needed to post an error that makes the most sense with line breaks, like I showed above: in the properly formatted version of New python executables in MYENV/bin/python3.4 Also creating executable in MYENV/bin/python Installing setuptools, pip, wheel...done. – mpacer Aug 4 '15 at 9:34
  • 1
    But why do you need to copy/paste the entire code block? – Patrick Hofman Aug 4 '15 at 9:35
  • So other people who run into this kind of error have a better chance at finding the SE post with subsets of those error codes — without sacrificing legibility in the actual comments. Again…that's only one use case, I'm happy to postulate others. But I can vouch for finding the thread via an error search + trying to comment with that text. The idea is that this functionality can be stopped from being abused with a simple detector on how vertically large the comment box is allowed to get. If it tries to format it and there is an error either raise a warning or don't let the comment be submitted. – mpacer Aug 4 '15 at 9:35
  • 1
    @mpacer, comments aren't searchable (with the Stack Exchange search engine), so putting code blocks into comments isn't going to help others who use the Stack Exchange search engine to search to find anything. Anyway, I'm not sure how putting the code block in a comment is the right way to help others find the question. If it's relevant to the question (or answer), edit the question to improve the question (or answer) by including it there. – D.W. Aug 5 '15 at 1:30
  • That is only a single instance of why this can be useful. Merely being able to communicate errors to the original author is useful. Also I don't know anyone who uses stack exchange’s search primarily compared to google or duckduckgo, which have both sent me to SE comments for specifically linked errors. And a summarization may not always be possible if you don't know how to summarize something efficiently but still can tell that it would be relevant to the answers’ author but not the original questions author. – mpacer Aug 5 '15 at 4:59
  • Comments are temporary. You shouldn't put vital important information in there. – Patrick Hofman Aug 5 '15 at 5:03
2

Data. You need data. Right now your argument consists solely of your personal opinion. The way to make your argument more convincing is to try to find data.

In particular, I think to justify your proposal, you would need a set of concrete examples where posting multi-line comments is valuable: i.e., specific examples of comments that would have been better with this feature. In the one example you gave, I think your comment would have been even clearer without trying to include a 3-line error message, but instead explaining in English what the problem with the answer is.

So, I suggest that you try to accumulate a list of examples that demonstrate where this would be valuable... and then try to find a way to evaluate just how often this arises. (Going by my own personal experience, I can't remember a case when I would have wanted this, so without data showing the contrary, I'd be inclined to suspect it's very rare that this would offer any benefit.)

  • I intended there to be 3 instances that I compiled: converting answers with code blocks to comments, Python or other white space sensitive code blocks that comment on but do not modify the answer, and error return values that are hard to follow if you either don't know how to summarize them (with that problem being made worse if what little formatting there is in those errors is destroyed). Regardless, I appreciate you taking the time to tell me how to improve this and not just to dismiss the point. Much more welcoming and super helpful; I wish I could +1 more than once. – mpacer Aug 5 '15 at 4:56

You must log in to answer this question.

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