如何在 Ruby 中评论多行?
#!/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.
这就是它的外观(通过屏幕截图) - 否则很难解释上述评论的外观。点击放大:
https://i.stack.imgur.com/AnchE.png
=begin
My
multiline
comment
here
=end
#
和空格?这是很多击键,尤其是当我开始添加换行符时。
尽管存在 =begin
和 =end
,正常且更正确的注释方式是在每一行使用 #
。如果您阅读任何 ruby 库的源代码,您会发现这几乎是所有情况下的多行注释方式。
#
,因为它更明显。在注释掉代码时,重要的是要明确这就是发生的事情。如果您在没有使用代码着色的编辑器中查看代码,使用 =begin/=end
可能很难弄清楚代码被忽略的原因。
#
注释。 (我很困惑为什么这有两个反对意见。我猜 Stack Overflow 社区有时会弄错!)
3 == three
其中 def three; 1 + 1 + 1 end
。因此两者都是有效的。谁在乎?使用3
!
vi
时。在这种情况下,无论如何,您可能不应该在那里进行开发。
#!/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!"
/*I am a\n#nested\ncomment, which really serves no purpose*/
/*I am bound /*to*/ FAIL!*/
如果您在多行注释中包含单行注释和代码(例如您不希望人们使用但又不想删除的带有文档的函数),这可能是有意义的从文件中。
使用任一:
=begin This is a comment block =end
或者
# This # is # a # comment # block
是 rdoc 目前支持的仅有的两个,我认为这是只使用这些的一个很好的理由。
=begin
或 #
的另一个好理由是 <<-DOC
和 "
语法都会在执行时生成无用的字符串文字。
=begin
comment line 1
comment line 2
=end
确保 =begin
和 =end
是该行的第一件事(没有空格)
=begin
(some code here)
=end
和
# This code
# on multiple lines
# is commented out
都是正确的。第一种注释的优点是可编辑性——取消注释更容易,因为删除的字符更少。第二种注释的优点是可读性——逐行阅读代码,更容易判断某行已被注释掉。您的电话,但请考虑谁会追随您,以及他们阅读和维护的难易程度。
=begin
和 =end
并没有直观地传达介于两者之间的是评论……例如,Clojure 使用 (comment :whatever)
,它在线索处说明了它的含义:stackoverflow.com/questions/1191628/block-comments-in-clojure
这是一个例子:
=begin
print "Give me a number:"
number = gets.chomp.to_f
total = number * 10
puts "The total value is : #{total}"
=end
您放置在 =begin
和 =end
之间的所有内容都将被视为注释,无论它包含多少行代码。
注意:确保 =
和 begin
之间没有空格:
正确:=开始
错误:=开始
如果有人正在寻找一种在 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 %>
这将起作用。
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 引擎无法正确呈现语法着色。测试它在您选择的编辑器中的呈现方式是一项练习。 ;)
#
而不是所有这些,主要是因为它在视觉上比=begin
/=end
更好地分隔注释行或使用 here-to 方法。而且,干得好。=begin
和=end
前面不能有任何空格。=begin...=end
和最后一个使用#
的块被 rdoc 在生成文档时拾取。