A case for "real" multiline comments

[Cameron Simpson]

On 19Apr2012 15:13, Chris Angelico <rosuav at gmail.com> wrote:
| On Thu, Apr 19, 2012 at 2:29 PM, Cameron Simpson <cs at zip.com.au> wrote:
| > On 18Apr2012 22:07, Jordan Perr <jordan at jperr.com> wrote:
| > | I came across this case while debugging some Python code that contained an
| > | error stemming from the use of multiline strings as comments. The code
| > | contained a very long list of objects, and I had commented out some of the
| > | objects using the multiline string.
| >
| > You are aware that a string is not a comment?
| 
| They're often (ab)used as comments, since Python lacks a multiline
| comment facility. Even docstrings are really comments in disguise.

Bah! To get into a function's docstring they need to be parsed by the
Python compiler. Ergo, not comments.

Calling them comments in disguise is a bit of a stretch.

| > I'd just do this:
| >
| >  list = [
| >  Object1(arg),
| >  ## Object2(arg),
| >  ## Object3(arg),
| >  Object4(arg)
| >  ]
| >
| > Multiple lines of single line comments. Frankly, I find this much easier
| > to see (all the disabled lines are delineated with nice bright comment
| > markers, and the beginning and end of the comment (were it a multiline
| > comment) can't disappear off my screen.
| >
| > I would say you've made a case _against_ multiline coments.
| 
| On the contrary, he has definitely made a case for multiline comments.

Sorry, he's made a misparsed program (not parsed as he intended) by
using a string where he should have used a comment? And because of this
he says we need (or should want) multiline comments? A multiline comment
can just as easily be misused to similar effect:

  list = [
  Object1(arg) /* bored now
  Object2(arg),
  Object3(arg),
  */
  Object4(arg)
  ]

I'd be more included to call implicit string concatenation a syntax
flaw, for all that it makes breaking strings us pretty nice.

| You just happen to disagree, and you prefer single line comments. :)

With cited reasons.

A multiline comment can have its top or bottom off the screen, so the
reader need not know they're looking at commented out code. And the
number of parse errors I've seen where the offending comment opener was
WAY WAY back in the code because someone forgot or removed a closing
comment marker is huge.

| I like multiline comments, but they do have their associated problems,
| most notably nesting. It gets quite awkward commenting out code that
| searches for comment markers, too.
| Perhaps what's needed is not a C-style /* */ comment marker, but
| something which must always be on a line of its own, and can therefore
| ONLY delimit entire-line comments. Something like what's often done
| with a preprocessor #if 0 #endif pair.

Which are also something of a pain to match up, leading to (hopefully
correctly labelled) #endifs thus:

  #endif /* !FEATUREMACRO */

I realise I could paint myself into opposing all multiline constructs,
especially loops and ifs, but I am generally quite happy with single
line comments. For one thing, they pretty much force you to mark all the
lines with leading comment syntax; you can't ever be misled.

| There's no way you can "lose"
| the #endif at the end of a line,

True.

Cheers,
-- 
Cameron Simpson <cs at zip.com.au> DoD#743
http://www.cskk.ezoshosting.com/cs/

It's better,  when you're racing with someone you don't know so well,
to stick to the inside line - it's easier to avoid the bits.
        - Barry Sheene, bike GP commentator