[ruby-trunk - Feature #7639][Open] More freedom for location of comments

Ruby Development
1

Issue #7639 has been reported by sawa (Tsuyoshi Sawada).

Feature #7639: More freedom for location of comments

Author: sawa (Tsuyoshi Sawada)
Status: Open
Priority: Normal
Assignee:
Category:
Target version:

When we chain methods with the period at the end of each line, we can
put comments in between the lines:

[1, 2, 3].
# First, we do blah blah
method1.
# Second, we do blah blah
method2.
=begin
  Third, the following line
  does this
  and that ...
=end
method3

but when we have the period at the beginning of the line, putting
comments in similar positions returns an error:

[1, 2, 3]
# First, we do blah blah
.method1
# Second, we do blah blah
.method2
=begin
  Third, the following line
  does this
  and that ...
=end
.method3

# => Error

It is confusing that putting comments between lines in a method chain is
sometimes allowed and sometimes not. I think it would be convenient if
comments are allowed in these positions even when the following line
starts with a period, and I request this as a feature. Currently, it
returns an error, which means that, if such syntax were allowed, there
would be no conflict with the existing syntax.

Furthermore, putting the period at the beginning of a line is suited for
method chains because the period will visually work as bullets, and it
makes more sense to have comments right before those lines.

2

Issue #7639 has been updated by nobu (Nobuyoshi N.).

Category set to core
Target version set to Next Major

Feature #7639: More freedom for location of comments

Author: sawa (Tsuyoshi Sawada)
Status: Open
Priority: Normal
Assignee:
Category: core
Target version: Next Major

When we chain methods with the period at the end of each line, we can
put comments in between the lines:

[1, 2, 3].
# First, we do blah blah
method1.
# Second, we do blah blah
method2.
=begin
  Third, the following line
  does this
  and that ...
=end
method3

but when we have the period at the beginning of the line, putting
comments in similar positions returns an error:

[1, 2, 3]
# First, we do blah blah
.method1
# Second, we do blah blah
.method2
=begin
  Third, the following line
  does this
  and that ...
=end
.method3

# => Error

It is confusing that putting comments between lines in a method chain is
sometimes allowed and sometimes not. I think it would be convenient if
comments are allowed in these positions even when the following line
starts with a period, and I request this as a feature. Currently, it
returns an error, which means that, if such syntax were allowed, there
would be no conflict with the existing syntax.

Furthermore, putting the period at the beginning of a line is suited for
method chains because the period will visually work as bullets, and it
makes more sense to have comments right before those lines.

3

Issue #7639 has been updated by duerst (Martin Dürst).

I think I disagree. The fact that comments before lines starting with a
dot are currently disallowed may be an artefact of how it was
implemented (or it may have been intended from the start). But in the
end, I think it is a feature. Usually, people check the end of a line to
find out whether the statement continues on the next line. For lines
starting with a dot, they have to check the start of the next line. If
we allow comments between these lines, there is no limit for how far one
has to check to find out whether the statement is over or continues. The
next line starting with a dot could be a hundred lines away or a
thousand or more lines away. That’s why I think it’s a good idea to not
allow comments before lines starting with a dot.

Feature #7639: More freedom for location of comments

Author: sawa (Tsuyoshi Sawada)
Status: Open
Priority: Normal
Assignee:
Category: core
Target version: Next Major

When we chain methods with the period at the end of each line, we can
put comments in between the lines:

[1, 2, 3].
# First, we do blah blah
method1.
# Second, we do blah blah
method2.
=begin
  Third, the following line
  does this
  and that ...
=end
method3

but when we have the period at the beginning of the line, putting
comments in similar positions returns an error:

[1, 2, 3]
# First, we do blah blah
.method1
# Second, we do blah blah
.method2
=begin
  Third, the following line
  does this
  and that ...
=end
.method3

# => Error

It is confusing that putting comments between lines in a method chain is
sometimes allowed and sometimes not. I think it would be convenient if
comments are allowed in these positions even when the following line
starts with a period, and I request this as a feature. Currently, it
returns an error, which means that, if such syntax were allowed, there
would be no conflict with the existing syntax.

Furthermore, putting the period at the beginning of a line is suited for
method chains because the period will visually work as bullets, and it
makes more sense to have comments right before those lines.

4

Issue #7639 has been updated by knu (Akinori MUSHA).

It’s all about the implementation cost because this is not a bug.
How about taking a glance at the lexer & parser code to see if it’s
worth it?

Feature #7639: More freedom for location of comments

Author: sawa (Tsuyoshi Sawada)
Status: Open
Priority: Normal
Assignee:
Category: core
Target version: Next Major

When we chain methods with the period at the end of each line, we can
put comments in between the lines:

[1, 2, 3].
# First, we do blah blah
method1.
# Second, we do blah blah
method2.
=begin
  Third, the following line
  does this
  and that ...
=end
method3

but when we have the period at the beginning of the line, putting
comments in similar positions returns an error:

[1, 2, 3]
# First, we do blah blah
.method1
# Second, we do blah blah
.method2
=begin
  Third, the following line
  does this
  and that ...
=end
.method3

# => Error

It is confusing that putting comments between lines in a method chain is
sometimes allowed and sometimes not. I think it would be convenient if
comments are allowed in these positions even when the following line
starts with a period, and I request this as a feature. Currently, it
returns an error, which means that, if such syntax were allowed, there
would be no conflict with the existing syntax.

Furthermore, putting the period at the beginning of a line is suited for
method chains because the period will visually work as bullets, and it
makes more sense to have comments right before those lines.

5

Issue #7639 has been updated by sawa (Tsuyoshi Sawada).

durst:

I don’t think your concern is warranted. In the use case that I showed,
the comments will be a description about what will immediately follow.
It would be there to signify the reader what something is going to
continue; if it works in the other way, then the content of the comment
would be the cause of badness. I am not suggesting to insert irrelevant
comments in between a chain. I would go against that.

Regarding your concern: “The next line starting with a dot could be a
hundred lines away or a thousand or more lines away.”, that is not to
blame the syntax. Putting a comment that long in the middle of a chain
is a bad coding style, irrespective of whether the next code line starts
with a period.

Feature #7639: More freedom for location of comments

Author: sawa (Tsuyoshi Sawada)
Status: Open
Priority: Normal
Assignee:
Category: core
Target version: Next Major

When we chain methods with the period at the end of each line, we can
put comments in between the lines:

[1, 2, 3].
# First, we do blah blah
method1.
# Second, we do blah blah
method2.
=begin
  Third, the following line
  does this
  and that ...
=end
method3

but when we have the period at the beginning of the line, putting
comments in similar positions returns an error:

[1, 2, 3]
# First, we do blah blah
.method1
# Second, we do blah blah
.method2
=begin
  Third, the following line
  does this
  and that ...
=end
.method3

# => Error

It is confusing that putting comments between lines in a method chain is
sometimes allowed and sometimes not. I think it would be convenient if
comments are allowed in these positions even when the following line
starts with a period, and I request this as a feature. Currently, it
returns an error, which means that, if such syntax were allowed, there
would be no conflict with the existing syntax.

Furthermore, putting the period at the beginning of a line is suited for
method chains because the period will visually work as bullets, and it
makes more sense to have comments right before those lines.

6

Issue #7639 has been updated by duerst (Martin Dürst).

Assignee set to matz (Yukihiro M.)

sawa (Tsuyoshi Sawada) wrote:

duerst:

(please call me Martin)

I agree that bad comments (too long, unrelated to what’s going on,…)
are bad, and we should not be too concerned with that. However, that is
not my main point.

My main point is that currently in Ruby, I can look at the end of a line
or at the start of the next line to know whether a statement/expression
continues on the next line. If we allow comment lines before lines
starting with a dot, this is no longer the case. I have to read past the
comment to find the next non-comment line to know whether the statement
is continued or not.

Currently, in 100%, I know that I don’t have to look past a comment to
check for a line starting with a dot. If we introduce this proposal,
there will still be about 99% of case where the statement does not
continue after the comment, and therefore most people may easily miss a
continuation after a comment. That’s the problem I see with this
proposal, and that problem does not go away even if all comments are
good ones.

Looking at your proposal again, it seems to me that you are saying that
this is an inconsistency for people who write the code. But I think it
is because we want it to be easy for people to read the code (without
having to look ahead past comments to check for continuations).

I have assigned this to Matz, because he has the most ability and
experience to jugde this kind of writability/readability issue.

Feature #7639: More freedom for location of comments

Author: sawa (Tsuyoshi Sawada)
Status: Open
Priority: Normal
Assignee: matz (Yukihiro M.)
Category: core
Target version: Next Major

When we chain methods with the period at the end of each line, we can
put comments in between the lines:

[1, 2, 3].
# First, we do blah blah
method1.
# Second, we do blah blah
method2.
=begin
  Third, the following line
  does this
  and that ...
=end
method3

but when we have the period at the beginning of the line, putting
comments in similar positions returns an error:

[1, 2, 3]
# First, we do blah blah
.method1
# Second, we do blah blah
.method2
=begin
  Third, the following line
  does this
  and that ...
=end
.method3

# => Error

It is confusing that putting comments between lines in a method chain is
sometimes allowed and sometimes not. I think it would be convenient if
comments are allowed in these positions even when the following line
starts with a period, and I request this as a feature. Currently, it
returns an error, which means that, if such syntax were allowed, there
would be no conflict with the existing syntax.

Furthermore, putting the period at the beginning of a line is suited for
method chains because the period will visually work as bullets, and it
makes more sense to have comments right before those lines.

7

Issue #7639 has been updated by sawa (Tsuyoshi Sawada).

I would like to add another argument for such feature. It is common that
you put each step of a chain in a new line. During debugging, it
frequently happens that you want to comment out particular lines within
a chain. You have no problem when the period is at the end of a line.
Below is an example of commenting out method2:

[1, 2, 3].
method1.
# method2{...}.
method3(arg1, arg2){...}.
method4{...}

But if you had the periods at the beginning of a line, you cannot do
this. The following will not be interpreted with the intended result.

[1, 2, 3]
.method1
# .method2{...}
.method3(arg1, arg2){...}
.method4{...}

Just for the purpose of commenting out method2, you would have to
temporarily move the period from the front of method3 to the end of
method1 as so:

[1, 2, 3]
.method1.
# .method2{...}
method3(arg1, arg2){...}
.method4{...}

This pretty much discourages programmers to write with the period at the
beginning of a line in the first place. It appears to me that such
inflexibility with the location of comments makes the feature of
allowing the period at the beginning of a line useless.

Feature #7639: More freedom for location of comments

Author: sawa (Tsuyoshi Sawada)
Status: Open
Priority: Normal
Assignee: matz (Yukihiro M.)
Category: core
Target version: Next Major

When we chain methods with the period at the end of each line, we can
put comments in between the lines:

[1, 2, 3].
# First, we do blah blah
method1.
# Second, we do blah blah
method2.
=begin
  Third, the following line
  does this
  and that ...
=end
method3

but when we have the period at the beginning of the line, putting
comments in similar positions returns an error:

[1, 2, 3]
# First, we do blah blah
.method1
# Second, we do blah blah
.method2
=begin
  Third, the following line
  does this
  and that ...
=end
.method3

# => Error

It is confusing that putting comments between lines in a method chain is
sometimes allowed and sometimes not. I think it would be convenient if
comments are allowed in these positions even when the following line
starts with a period, and I request this as a feature. Currently, it
returns an error, which means that, if such syntax were allowed, there
would be no conflict with the existing syntax.

Furthermore, putting the period at the beginning of a line is suited for
method chains because the period will visually work as bullets, and it
makes more sense to have comments right before those lines.

8

Issue #7639 has been updated by nobu (Nobuyoshi N.).

Description updated

Feature #7639: More freedom for location of comments

Author: sawa (Tsuyoshi Sawada)
Status: Feedback
Priority: Normal
Assignee: matz (Yukihiro M.)
Category: core
Target version: Next Major

=begin
When we chain methods with the period at the end of each line, we can
put comments in between the lines:

[1, 2, 3].
# First, we do blah blah
method1.
# Second, we do blah blah
method2.
=begin
  Third, the following line
  does this
  and that ...
=end
method3

but when we have the period at the beginning of the line, putting
comments in similar positions returns an error:

[1, 2, 3]
# First, we do blah blah
.method1
# Second, we do blah blah
.method2
=begin
  Third, the following line
  does this
  and that ...
=end
.method3

# => Error

It is confusing that putting comments between lines in a method chain is
sometimes allowed and sometimes not. I think it would be convenient if
comments are allowed in these positions even when the following line
starts with a period, and I request this as a feature. Currently, it
returns an error, which means that, if such syntax were allowed, there
would be no conflict with the existing syntax.

Furthermore, putting the period at the beginning of a line is suited for
method chains because the period will visually work as bullets, and it
makes more sense to have comments right before those lines.
=end

9

Issue #7639 has been updated by nobu (Nobuyoshi N.).

Status changed from Open to Feedback

Comments are equivalent to white spaces syntactically now, so do you
expect that a method chain will continue beyond empty lines?
It seems strange to me.

Feature #7639: More freedom for location of comments

Author: sawa (Tsuyoshi Sawada)
Status: Feedback
Priority: Normal
Assignee: matz (Yukihiro M.)
Category: core
Target version: Next Major

When we chain methods with the period at the end of each line, we can
put comments in between the lines:

[1, 2, 3].
# First, we do blah blah
method1.
# Second, we do blah blah
method2.
=begin
  Third, the following line
  does this
  and that ...
=end
method3

but when we have the period at the beginning of the line, putting
comments in similar positions returns an error:

[1, 2, 3]
# First, we do blah blah
.method1
# Second, we do blah blah
.method2
=begin
  Third, the following line
  does this
  and that ...
=end
.method3

# => Error

It is confusing that putting comments between lines in a method chain is
sometimes allowed and sometimes not. I think it would be convenient if
comments are allowed in these positions even when the following line
starts with a period, and I request this as a feature. Currently, it
returns an error, which means that, if such syntax were allowed, there
would be no conflict with the existing syntax.

Furthermore, putting the period at the beginning of a line is suited for
method chains because the period will visually work as bullets, and it
makes more sense to have comments right before those lines.

10

Issue #7639 has been updated by alexeymuranov (Alexey M.).

As for me, i do not like to continue a line by starting the following
one with a dot: it is not clear immediately if the first line is over,
and does not allow to copy-paste the code into IRB.

Feature #7639: More freedom for location of comments

Author: sawa (Tsuyoshi Sawada)
Status: Feedback
Priority: Normal
Assignee: matz (Yukihiro M.)
Category: core
Target version: Next Major

=begin
When we chain methods with the period at the end of each line, we can
put comments in between the lines:

[1, 2, 3].
# First, we do blah blah
method1.
# Second, we do blah blah
method2.
=begin
  Third, the following line
  does this
  and that ...
=end
method3

but when we have the period at the beginning of the line, putting
comments in similar positions returns an error:

[1, 2, 3]
# First, we do blah blah
.method1
# Second, we do blah blah
.method2
=begin
  Third, the following line
  does this
  and that ...
=end
.method3

# => Error

It is confusing that putting comments between lines in a method chain is
sometimes allowed and sometimes not. I think it would be convenient if
comments are allowed in these positions even when the following line
starts with a period, and I request this as a feature. Currently, it
returns an error, which means that, if such syntax were allowed, there
would be no conflict with the existing syntax.

Furthermore, putting the period at the beginning of a line is suited for
method chains because the period will visually work as bullets, and it
makes more sense to have comments right before those lines.
=end

11

Issue #7639 has been updated by sawa (Tsuyoshi Sawada).

alexeymuranov (Alexey M.)

Allowing a line to start with a period was a change introduced in Ruby
1.9. It is not what I am newly proposing here. If you are against it,
that would be a claim against that feature introduced in the past. My
proposal is, provided such feature was introduced, trying to make
maximum sense out of it.

Feature #7639: More freedom for location of comments

Author: sawa (Tsuyoshi Sawada)
Status: Feedback
Priority: Normal
Assignee: matz (Yukihiro M.)
Category: core
Target version: Next Major

=begin
When we chain methods with the period at the end of each line, we can
put comments in between the lines:

[1, 2, 3].
# First, we do blah blah
method1.
# Second, we do blah blah
method2.
=begin
  Third, the following line
  does this
  and that ...
=end
method3

but when we have the period at the beginning of the line, putting
comments in similar positions returns an error:

[1, 2, 3]
# First, we do blah blah
.method1
# Second, we do blah blah
.method2
=begin
  Third, the following line
  does this
  and that ...
=end
.method3

# => Error

It is confusing that putting comments between lines in a method chain is
sometimes allowed and sometimes not. I think it would be convenient if
comments are allowed in these positions even when the following line
starts with a period, and I request this as a feature. Currently, it
returns an error, which means that, if such syntax were allowed, there
would be no conflict with the existing syntax.

Furthermore, putting the period at the beginning of a line is suited for
method chains because the period will visually work as bullets, and it
makes more sense to have comments right before those lines.
=end

12

Issue #7639 has been updated by sawa (Tsuyoshi Sawada).

Indeed, method chains do seem to continue beyond empty lines. The
following two work:

[1, 2, 3].

map{|x| x * 2}

[1, 2, 3].

map{|x| x * 2}

But the following does not, (which I claim is strange, given that the
above two work):

[1, 2, 3]

.map{|x| x * 2}

Feature #7639: More freedom for location of comments

Author: sawa (Tsuyoshi Sawada)
Status: Feedback
Priority: Normal
Assignee: matz (Yukihiro M.)
Category: core
Target version: Next Major

=begin
When we chain methods with the period at the end of each line, we can
put comments in between the lines:

[1, 2, 3].
# First, we do blah blah
method1.
# Second, we do blah blah
method2.
=begin
  Third, the following line
  does this
  and that ...
=end
method3

but when we have the period at the beginning of the line, putting
comments in similar positions returns an error:

[1, 2, 3]
# First, we do blah blah
.method1
# Second, we do blah blah
.method2
=begin
  Third, the following line
  does this
  and that ...
=end
.method3

# => Error

It is confusing that putting comments between lines in a method chain is
sometimes allowed and sometimes not. I think it would be convenient if
comments are allowed in these positions even when the following line
starts with a period, and I request this as a feature. Currently, it
returns an error, which means that, if such syntax were allowed, there
would be no conflict with the existing syntax.

Furthermore, putting the period at the beginning of a line is suited for
method chains because the period will visually work as bullets, and it
makes more sense to have comments right before those lines.
=end

13

Issue #7639 has been updated by knu (Akinori MUSHA).

It was meant to be and has been an experimental feature, so let’s not
take it for granted as established one.
We already have it so why not extend it is not the way to go.
If a problem is found, we need to reconsider and address downsides
before it’s too late.

I personally think that this line continuation rule should be
withdrawn/obsoleted because it is one of few exceptions that breaks the
golden general rule that “If a statement is syntactically complete at a
line end, then it is the end of the statement.”

Feature #7639: More freedom for location of comments

Author: sawa (Tsuyoshi Sawada)
Status: Feedback
Priority: Normal
Assignee: matz (Yukihiro M.)
Category: core
Target version: Next Major

=begin
When we chain methods with the period at the end of each line, we can
put comments in between the lines:

[1, 2, 3].
# First, we do blah blah
method1.
# Second, we do blah blah
method2.
=begin
  Third, the following line
  does this
  and that ...
=end
method3

but when we have the period at the beginning of the line, putting
comments in similar positions returns an error:

[1, 2, 3]
# First, we do blah blah
.method1
# Second, we do blah blah
.method2
=begin
  Third, the following line
  does this
  and that ...
=end
.method3

# => Error

It is confusing that putting comments between lines in a method chain is
sometimes allowed and sometimes not. I think it would be convenient if
comments are allowed in these positions even when the following line
starts with a period, and I request this as a feature. Currently, it
returns an error, which means that, if such syntax were allowed, there
would be no conflict with the existing syntax.

Furthermore, putting the period at the beginning of a line is suited for
method chains because the period will visually work as bullets, and it
makes more sense to have comments right before those lines.
=end