Project

General

Profile

Actions

Feature #20405

open

Inline comments

Added by nobu (Nobuyoshi Nakada) about 1 year ago. Updated about 11 hours ago.

Status:
Open
Assignee:
-
Target version:
-
[ruby-core:117392]

Description

I propose a new inline comment syntax.

p (| This is a comment (| and nested one |) /:|) (:|) #=> :|

Updated by vo.x (Vit Ondruch) about 1 year ago

I like this proposal. But there are other possibilities, such as:

(: This is comment :)

That would just underline Ruby as a "happy" language. Of course variants such as (-: ... :-) or even (o: ... :o) could even extend the expressiveness of comments

Updated by nobu (Nobuyoshi Nakada) about 1 year ago

vo.x (Vit Ondruch) wrote in #note-1:

I like this proposal. But there are other possibilities, such as:

(: This is comment :)

Thank you for the comment, but you may know (: can conflict existing code.
The reason I selected (| is that /:|) is used as Matz's face (no beard version).

Updated by matheusrich (Matheus Richard) about 1 year ago · Edited

I think, unironically, this could be a nice addition. Maybe with a syntax closer to the current comments?

p #= This is a comment #= and nested one =# =# :| # => :|

Updated by pabloh (Pablo Herrero) 10 months ago

This could be particularly useful for projects like rbs-inline.

Updated by make_now_just (Hiroya Fujinami) 20 days ago

I'd propose (= ... =) for inline comments because Ruby already has =begin and =end syntax and it seems to relate to that.

p (= ^..^ =) :nyan

Also, I believe that (= ... =) does not break the current syntax.

Updated by nobu (Nobuyoshi Nakada) 20 days ago · Edited

make_now_just (Hiroya Fujinami) wrote in #note-5:

p (= ^..^ =) :nyan

Cool.

Updated by make_now_just (Hiroya Fujinami) about 11 hours ago

Using type checkers makes it difficult to write Ruby fluently. To make type checkers work effectively in Ruby, we need to add numerous annotations, and these annotations are done via comments. However, Ruby only has line comments. This restricts our ability to annotate specific parts of an expression or pinpoint locations within a line; we cannot, for instance, comment directly on an individual argument within a method's parameter list on the same line or a portion of a complex expression.

A prime example of this is type casting. To cast a specific argument of a method, we often have to resort to workarounds like inserting a line break in the middle of the argument list or adding variables solely for the type checker. In other words, we are forced to write clumsy Ruby code.
(In the following example, a pair of {= and =} is used for syntax of inline comments.)

# Before:
some_method(
  foo,
  [], #: Array[Integer]
  bar
)
# or
tmp_var_for_type_check = [] #: Array[Integer]
some_method(foo, tmp_var_for_type_check, bar)

# After:
some_method(foo, [] {= as Array[Integer] =}, bar)
# or
some_method(foo, [] {= of Integer =}, bar)

Personally, I find this unenjoyable and feel it detracts from the "Rubyishness" of the language. Therefore, I believe that introducing inline comments is necessary to improve this situation.

Introducing inline comments also brings the advantage of enabling previously impossible annotations. These capabilities would further enrich Ruby's expressiveness.

# Passing generic type parameters at the appropriate location
some_generics_method{= [Int, String] =}(foo, bar)

# Locally disabling code coverage
foo = cond ? 1 : {= :nocov: =} 2

# Commenting within percent literals
%w(
  foo bar #{= comment =}
  baz     #{= comment =}
)
Actions

Also available in: Atom PDF

Like4
Like0Like0Like0Like0Like2Like0Like0