multiline comments

[Sion Arrowsmith]

Is it harder to remove "n" lines of code commented out with "#" than "n"
lines of multiline commented code? How?

I'd say it's harder to remove the latter, due to having to search for
the end of comment sequence, rather than simply looking for where the
block comment stops. And you've extra problems if you allow nested
comments, because then you'll have to count how deep you've gone. Of
course, if you can completely trust your editor's syntax highlighter
you might be OK, but wasn't part of the point of this argument about
not *requiring* smart editors to be productive?

 

[Jorge Godoy]

I'd say it's harder to remove the latter, due to having to search for
the end of comment sequence, rather than simply looking for where the
block comment stops. And you've extra problems if you allow nested
comments, because then you'll have to count how deep you've gone. Of
course, if you can completely trust your editor's syntax highlighter
you might be OK, but wasn't part of the point of this argument about
not *requiring* smart editors to be productive?

Also, if you remove the start of the block first, then your editor might not
be highlighting anymore... With nested comments things get even worse
because you might miss the end of the outer block or something like that.

--
Jorge Godoy <[email protected]>

"Quidquid latine dictum sit, altum sonatur."
- Qualquer coisa dita em latim soa profundo.
- Anything said in Latin sounds smart.

 

[rx]

Typing (* and *) on a few line will always be quicker, easier, and less
confusing than any rcs diffs/restores. Once you delete the code you can
no longer see it or add pieces back in without retrieving it from an
external store. I'm not saying nested comments solve every problem, just
that there exists a certain (perhaps small) class of problems they solve
particularly well.

Personally, I rarely leave code commented out beyond a single coding
session. But my particular coding habits aren't relevant here.

Well I perfectly agree, and why make a dependence on external tools
(IDE/CVS) if you can build it into the language with no conflicts by using
some strange ascii combinations. I'm sure something like:

a()
(#
b()
c()
#)
d()

would be fine.

 

[Edward Elliott]

Really? Under what circumstances is it easier to see what's going on
with start/end comments than with comment-to-end-of-line?

Off the top of my head:
1. The code is usually easier to read as # can obscure the first token on
the line. This can be alleviated by leaving a space after the # or
coloring the # differently.

2. It's easier to see where a nested comment begins and ends. Instead of
counting #s at the beginning of lines, just find the matching closer. This
is fairly simple to automate in a good editor. Counting #s can be
automated as well, but fails if the programmer gets lazy and doesn't add
extra #s when nesting, i.e. turns this:

line 1
#line 2
line 3

into this

#line 1
#line 2
#line 3

instead of this

#line 1
##line 2
#line 3

3. Preserves history better. Say I have consecutive lines commented out.
With #s, all you see is this:

#line 1
#line 2
#line 3
#line 4

If they were commented out in two chunks at different times, multiline
comments can preserve that information:

(*
line 1
line 2
*)
(*
line 3
line 4
*)

This isn't meant to be an exhaustive list. There are ways to address all
these things with single-line comments, but it takes more work. Economy of
expression favors nested comments in my book.

Gregor has a good point about grep, but C-based languages with /**/ suffer
the same problem. I think the answer is smarter searches, not dumber comments.

 

[rx]

Edward Elliott wrote:

You can use either """ or '''. I don't keep changing them in my code, so
I
can always use the other type (usually I use " so for commenting things
out
I'd use ') to do that.

Try that on this code:

a=3
a=a*a
b='''This is a
very long
long
text'''
print a


like:

a=3
'''
a=a*a
b='''This is a
very long
long
text'''
'''
print a



raises SyntaxError

 

[Edward Elliott]

I'd say it's harder to remove the latter, due to having to search for
the end of comment sequence, rather than simply looking for where the
block comment stops.

Like I said, it's debatable. Depends on the editing conditions you assume.
It's easy to imagine situations where either type comes out ahead.

 

[Edward Elliott]

Edward Elliott wrote:
Try using Subversion. You can work and make diffs disconnected from the
network.

rcs isn't the issue. I'm already assuming a local store, a networked one
just makes my argument even easier.

I don't miss them.

Fair enough.

Well, I believe they are since it looks like a habit of yours to use
multiline comments. It is common for people coming from other programming
languages that support them.

Yes I cut my teeth on C, C++, and Java. That was a long time ago. I don't
miss them because they're more C-like (the C-family actually has an awful
implementation), I miss them because they're useful. Actually I never used
multiline much until I did a project in ML and saw how they should work.

However the last 4 years I've used Perl, Python, and PHP almost
exclusively. I'm used to single-line comments, I just find their
expressive power lacking. No shame in borrowing the best features of other
languages.

 

[rx]

Also, if you remove the start of the block first, then your editor might
not
be highlighting anymore... With nested comments things get even worse
because you might miss the end of the outer block or something like that.

I have commented out a lot of C++ code and miss the block feature in python
more than I missed the nested comments in C++.
Besides nothing really strange happened.
Sometimes you just need to dissable some of the code temporarly as quickly
as possible, and I like that it is not higlighted any more, since I will not
look into it before I dissable the comment.

 

[Edward Elliott]

discouraged except where vital. Perhaps we should make them really hard
and elegant - mandate latex/mathml markup so good editors can display
the equations we are implementing

I like this guy already!

 

[Edward Elliott]

You can use either """ or '''. I don't keep changing them in my code, so I
can always use the other type (usually I use " so for commenting things out
I'd use ') to do that.

It's close, only problem is it doesn't nest. It'll have to be good enough
for now.

If the latter can help, why not?

Because in this case it limits the expressive power of the language.
Multiline comments enable clearer communication of intent (see earlier post
for some reasons why).

 

[Jorge Godoy]

I have commented out a lot of C++ code and miss the block feature in
python more than I missed the nested comments in C++.
Besides nothing really strange happened.
Sometimes you just need to dissable some of the code temporarly as quickly
as possible, and I like that it is not higlighted any more, since I will
not look into it before I dissable the comment.

This is how I do it: select the lines I want to comment and ask Emacs to
comment that region. It is the same command and method for "n" different
languages and I don't care if there is multiline comment support or not.
It is really as fast as inserting /* and ending with */ (in fact, I type
less than to achieve that since I only use three keys, counting the
Ctrl-Space to start the block).

--
Jorge Godoy <[email protected]>

"Quidquid latine dictum sit, altum sonatur."
- Qualquer coisa dita em latim soa profundo.
- Anything said in Latin sounds smart.

 

[Jorge Godoy]

Try that on this code:

a=3
a=a*a
b='''This is a
very long
long
text'''
print a


like:

a=3
'''
a=a*a
b='''This is a
very long
long
text'''
'''
print a



raises SyntaxError

Of course! You should have used """ since you already used ''' in your
triple-quoted text. But I'm just repeating what I already said (and kept
above so that you can see it again).

--
Jorge Godoy <[email protected]>

"Quidquid latine dictum sit, altum sonatur."
- Qualquer coisa dita em latim soa profundo.
- Anything said in Latin sounds smart.

 

[rx]

This is how I do it: select the lines I want to comment and ask Emacs to
comment that region. It is the same command and method for "n" different
languages and I don't care if there is multiline comment support or not.
It is really as fast as inserting /* and ending with */ (in fact, I type
less than to achieve that since I only use three keys, counting the
Ctrl-Space to start the block).

It would be much nicer to have it in the language since there are many
editors and many ways to do what you do (it would also make it more easy to
make a editor).
Besides it could be done with two keys if that really important - but I
doubt it.
But in a way you are also right if you use more than a few languages in the
same editor, but then again the editor would still be able to do the
commenting if you prefered that.
I don't understand the problem - why should comments (and I hope you believe
there should be a one line comment at least) be restricted to one line.
It doesn't work that way for if, while, for.

 

[Jorge Godoy]

I don't understand the problem - why should comments (and I hope you
believe there should be a one line comment at least) be restricted to one
line. It doesn't work that way for if, while, for.

It is the minimum case that can solve a problem commenting one line -- or
part of it as in "print '3' # print the number 3" -- or commenting multiple
lines. It is also easier to deal with since you don't have to end your
comment all the time.

For "if", "while", "for", etc. you have ":" and the indentation. You don't
have an "endif", "endwhile", "endfor" (so, why having an "end comment"?).

--
Jorge Godoy <[email protected]>

"Quidquid latine dictum sit, altum sonatur."
- Qualquer coisa dita em latim soa profundo.
- Anything said in Latin sounds smart.

 

[rx]

Of course! You should have used """ since you already used ''' in your
triple-quoted text. But I'm just repeating what I already said (and kept
above so that you can see it again).

Sorry - I should have read more carefully.
I like the idea and will use it I think.
Still a little strange to newcomers that there are three ways to do the same
and that you should be carefull to use the right '''/""" inside the comment
else the comment will not work for some reason.

#comment

'''
comment
'''

"""
comment
"""

 

[rx]

It is the minimum case that can solve a problem commenting one line -- or
part of it as in "print '3' # print the number 3" -- or commenting
multiple
lines. It is also easier to deal with since you don't have to end your
comment all the time.

For "if", "while", "for", etc. you have ":" and the indentation. You
don't
have an "endif", "endwhile", "endfor" (so, why having an "end comment"?).

There no reason why a multiple line comment couldn't be indented (then the
indentation is the end of comment in some sense), but I don't find that
logical - after all its my comment and I don't want python to tell me how to
indent it.

 

[Jorge Godoy]

Still a little strange to newcomers that there are three ways to do the
same and that you should be carefull to use the right '''/""" inside the
comment else the comment will not work for some reason.

#comment

'''
comment
'''

"""
comment
"""

Please, note that triple quotes are not for comments. They may be used like
that and they are used like that, but their primary intention is for
multiline strings (something like the here docs in Perl, for example).

Triple quotes can also be used like this:

usage = """
This program accepts the following options:

--help, -h Display this message
--verbose, -v Display more details
"""

This defines a multiline string. If you had to use only single quotes then
you'd have to insert "\n" for each newline.

--
Jorge Godoy <[email protected]>

"Quidquid latine dictum sit, altum sonatur."
- Qualquer coisa dita em latim soa profundo.
- Anything said in Latin sounds smart.

 

[OKB (not okblacke)]

Indeed. Using revision control means never needing to comment out
blocks of code.

If your revision control system is so inconvenient to use that you'd
rather have large blocks of commented-out code, it's time to start
using a better RCS -- perhaps a distributed one, so you can commit to
your own local repository with abandon while trying out changes.

I don't buy this kind of argument. It seems strange to say that
the language is designed a certain way because users are expected to use
certain kinds of third-party tools to manage their code. What if I'm
just putting together a little script to do something and I don't want
to mess with a revision control system?

--
--OKB (not okblacke)
Brendan Barnwell
"Do not follow where the path may lead. Go, instead, where there is
no path, and leave a trail."
--author unknown

 

[Ben Finney]

I don't buy this kind of argument. It seems strange to say
that the language is designed a certain way because users are
expected to use certain kinds of third-party tools to manage their
code.

You're reading a causal relationship where none was asserted.

What if I'm just putting together a little script to do something
and I don't want to mess with a revision control system?

If it's so little, why are single-line comments not enough?

If it's large enough that large blocks of code need changing
frequently, I assert revision control is needed.

The barriers to using a good revision control system are so low these
days it's poor practice to avoid using one for anything but throw-away
programs.

 

[Sion Arrowsmith]

Really? Under what circumstances is it easier to see what's going on
with start/end comments than with comment-to-end-of-line?

Off the top of my head:
[ ... ]

It appears to me that our fundamental difference is that you see value
in long-term preservation of sections of commented-out code without
any kind of real comment as to what's going on, whereas I consider
this to be appallingly bad practice.