Ruby 中的多行注释？答案

【问题标题】：Multi-Line Comments in Ruby?Ruby 中的多行注释？
【发布时间】：2011-02-28 16:56:34
【问题描述】：

如何在 Ruby 中注释多行？

【问题讨论】：

不幸的是，ruby 中的多行 cmets 看起来非常像代码块。考虑到这个问题的高分（以及公认的答案），研究 ruby 语法的人应该清楚地考虑一下。

标签： ruby comments multiline block-comments

【解决方案1】：

=begin
My 
multiline
comment
here
=end

【讨论】：

当然，您可以这样做。有用。这是非常罕见的。我觉得很难看。可能是我卡在了自己的方式上？
我发现如果我在 =begin 或 =end 之前包含一个选项卡，则 cmets 不起作用。 =begin 和 =end 都需要写在每一行的开头。
你并不孤单@DavidJames。我个人选择让我的编辑将它们全部注释掉。 CMD+/ 或 ALT+/ 是大多数人的约定。
@DavidJames，你会怎么做呢？在每一行之前输入# 和空格？这是很多击键，尤其是当我开始添加换行符时。

【解决方案2】：

#!/usr/bin/env ruby

=begin
Between =begin and =end, any number
of lines may be written. All of these
lines are ignored by the Ruby interpreter.
=end

puts "Hello world!"

【讨论】：

+1 因为我不知道嵌套是 Ruby 多行 cmets 中的一个东西。
@ParthianShot - 这不是一件事 - =begin 和 =end 如果不在行首，则将被忽略。嵌套似乎是不可能的。
在评论中嵌套评论会导致单个评论或尝试结束没有评论结束的评论时出现语法错误。 /*I am a\n#nested\ncomment, which really serves no purpose*/ /*I am bound /*to*/ FAIL!*/ 如果您在多行注释中有单行 cmets 和代码，例如带有文档的函数，您不希望人们使用，但您也不想删除它，这可能是有意义的从文件中。

【解决方案3】：

#!/usr/bin/env ruby

=begin
Every body mentioned this way
to have multiline comments.

The =begin and =end must be at the beginning of the line or
it will be a syntax error.
=end

puts "Hello world!"

<<-DOC
Also, you could create a docstring.
which...
DOC

puts "Hello world!"

"..is kinda ugly and creates
a String instance, but I know one guy
with a Smalltalk background, who
does this."

puts "Hello world!"

##
# most
# people
# do
# this


__END__

But all forgot there is another option.
Only at the end of a file, of course.

这就是它的外观（通过屏幕截图） - 否则很难解释上述 cmets 的外观。 点击放大：

【讨论】：

我真的更喜欢使用#而不是所有这些，主要是因为它在视觉上比=begin/=end更好地分隔注释行或使用here-to方法。而且，干得好。
有趣的是，这个答案使语法荧光笔中的一些缺陷显而易见。
别忘了=begin 和=end 前面不能有任何空格。
而且不能在方法中使用 =begin =end
需要注意的是，在上面的示例代码中，只有第一个 =begin...=end 和最后一个使用 # 的块在生成文档时被 rdoc 拾取。

【解决方案4】：

尽管存在=begin 和=end，但正常且更正确的注释方式是在每一行使用#。如果您阅读任何 ruby 库的源代码，您会发现在几乎所有情况下，多行 cmets 都是采用这种方式。

【讨论】：

你可能会得到关于你陈述中“更正确”部分的争论，因为它们都是有效的。我更喜欢使用#，因为它更明显。在注释掉代码时，重要的是要明确这就是发生的事情。如果您在使用 =begin/=end 的编辑器中查看代码时没有使用代码着色的好处，可能很难弄清楚代码被忽略的原因。
当然，有很多“有效”的方式来编写 cmets。让我们在这里实用。如果您实际编写 Ruby 并阅读其他人编写的内容，那么您应该使用 # cmets。（我很困惑为什么这有两个反对意见。我猜 Stack Overflow 社区有时会弄错！）
3 == three 其中def three; 1 + 1 + 1 end。因此两者都是有效的。谁在乎？使用3!
@theTinMan 虽然是这样，但通常唯一一次缺少语法突出显示（根据我的经验）是在生产服务器上使用 vi 时。在这种情况下，无论如何，您可能不应该在那里进行开发。
@DavidJames 你的例子很荒谬，因为它更冗长。对于较长的 cmets，在每一行上放置一个散列会更加冗长。如果有人认为短语“/dev/urandom 在这里用于非阻塞加密声音 PRNG。不要碰这个代码 - 它很神奇”是我编写 ruby 的尝试，我认为他们的困惑更多来自于对他们的无知部分不是我的不清楚。这并不是说您的观点总是无效的——这只是在注释掉代码时的一个好观点。但是，如果您的评论只是……评论……无论哪种方式都应该很清楚。

【解决方案5】：

=begin
(some code here)
=end

和

# This code
# on multiple lines
# is commented out

都是正确的。第一种注释的优点是可编辑性——取消注释更容易，因为删除的字符更少。第二种注释的优点是可读性——逐行阅读代码，更容易判断某行已被注释掉。你的电话，但想想谁会追随你，以及他们阅读和维护的难易程度。

【讨论】：

IMO、=begin 和 =end 并没有在视觉上传达介于两者之间的是评论……例如，Clojure 使用 (comment :whatever)，这在线索处说明了它的含义： stackoverflow.com/questions/1191628/block-comments-in-clojure
在 Java、C 和 C++ 中都没有“/*”和“*/”。与 Ruby 语法一样，可能会在这两个字符之间注释掉大块代码，了解该语言基础的每个人都知道它们的含义。
语法着色（例如在 vim 中）显示第一种类型是注释。在那种情况下，第一种类型没有缺点。

【解决方案6】：

使用任一：

=开始这是一种评论堵塞 =结束

或

＃这＃是＃一种＃评论＃堵塞

是 rdoc 目前支持的仅有的两个，我认为这是只使用这些的一个很好的理由。

【讨论】：

坚持使用=begin 或# 的另一个充分理由是<<-DOC 和" 语法都会在执行时生成无用的字符串文字。

【解决方案7】：

这是一个例子：

=begin 
print "Give me a number:"
number = gets.chomp.to_f

total = number * 10
puts  "The total value is : #{total}"

=end

您在=begin 和=end 之间放置的所有内容都将被视为注释，无论其中包含多少行代码。

注意：确保=和begin之间没有空格：

正确：=begin
错误：= begin

【讨论】：

【解决方案8】：

如果有人在 Ruby on Rails 中寻找在 html 模板中注释多行的方法，那么 =begin =end 可能会出现问题，例如：

<%
=begin
%>
  ... multiple HTML lines to comment out
  <%= image_tag("image.jpg") %>
<%
=end
%>

会因为 %> 关闭 image_tag 而失败。

在这种情况下，这是否是注释掉可能是有争议的，但我更喜欢用“if false”块括起不需要的部分：

<% if false %>
  ... multiple HTML lines to comment out
  <%= image_tag("image.jpg") %>
<% end %>

这会起作用。

【讨论】：

带有开头和结尾的多行注释，就像您的第一个代码 sn-p 一样，确实有效。

【解决方案9】：

=begin
comment line 1
comment line 2
=end

确保=begin 和=end 是该行的第一件事（没有空格）

【讨论】：

【解决方案10】：

  def idle
    <<~aid
    This is some description of what idle does.

    It does nothing actually, it's just here to show an example of multiline
    documentation. Thus said, this is something that is more common in the
    python community. That's an important point as it's good to also fit the
    expectation of your community of work. Now, if you agree with your team to
    go with a solution like this one for documenting your own base code, that's
    fine: just discuss about it with them first.

    Depending on your editor configuration, it won't be colored like a comment,
    like those starting with a "#". But as any keyword can be used for wrapping
    an heredoc, it is easy to spot anyway. One could even come with separated
    words for different puposes, so selective extraction for different types of
    documentation generation would be more practical. Depending on your editor,
    you possibly could configure it to use the same syntax highlight used for
    monoline comment when the keyword is one like aid or whatever you like.

    Also note that the squiggly-heredoc, using "~", allow to position
    the closing term with a level of indentation. That avoids to break the visual reading flow, unlike this far too long line.
    aid
  end

请注意，在发帖时，stackoverflow 引擎无法正确呈现语法着色。测试它在您选择的编辑器中的呈现方式是一项练习。 ;)

【讨论】：