如何在Ruby中使用注释

介绍

注释是计算机程序中被编译器和解释器忽略的行。您可以使用注释让其他程序员更容易理解您的程序，方法是使用它们来提供更多上下文或解释程序的每个部分正在做什么。此外，您可以使用注释来解释您选择特定解决方案的原因，甚至可以防止在您制定修复程序时临时执行程序中有问题或不完整的部分。

有些注释可能永远保留在代码中，例如解释上下文的注释，而其他注释可能是临时的，例如您在构建程序时留下的注释。

下面我们来看看如何在Ruby程序中使用注释来留下注释，以及如何将它们用作调试工具。

注释语法和用法

Ruby 中的注释以井号 (#) 开头，一直到行尾，如下所示：

# This is a comment in Ruby

虽然不是必需的，但您应该在井号之后放置一个空格以提高评论的可读性。

运行程序时，您不会在代码中看到任何注释指示； Ruby 解释器完全忽略它们。注释在源代码中供人类阅读，而不是供计算机执行。

在一个简单的 Ruby 程序中，例如教程如何编写您的第一个 Ruby 程序中的程序，您可以使用注释来提供有关代码各部分发生情况的更多详细信息：

问候.rb

# Display a prompt to the user
puts "Please enter your name."

# Save the input they type and remove the last character (the enter keypress)
name = gets.chop

# Print the output to the screen
puts "Hi, #{name}! I'm Ruby!"

这些注释让您大致了解程序的每个部分的作用以及它的工作原理。

在一个遍历数组并将其内容显示为 HTML 列表的程序中，您可能会看到这样的注释，它对代码的作用提供了更多解释：

鲨鱼.rb

sharks = ['hammerhead', 'great white', 'dogfish', 'frilled', 'bullhead', 'requiem']

# transform each entry in the array to an HTML entity, with leading spaces and a newline.
listitems = sharks.map{ |shark| "  <li>#{shark}</li>\n"}

# Print the opening <ul>, then print the array of list items
print "<ul>\n#{listitems.join}</ul>"

您可能还不熟悉 map 和 join 之类的东西，但这些注释让您了解该程序应该如何工作以及输出可能是什么样子。试试看。将此代码放在一个名为 sharks.rb 的文件中并运行它：

ruby sharks.rb

您将看到程序的输出：

Output<ul>
  <li>hammerhead</li>
  <li>great white</li>
  <li>dogfish</li>
  <li>frilled</li>
  <li>bullhead</li>
  <li>requiem</li>
</ul>

请注意，您看不到注释，因为解释器忽略了它们。但输出可能与您的预期相符。评论是一种很好的交流工具，尤其是当阅读评论的人不熟悉该语言时。

注释的缩进应该与他们注释的代码相同。也就是说，一个没有缩进的类定义将有一个没有缩进的注释，并且后面的每个缩进级别都会有与其正在注释的代码对齐的注释。

例如，这里是一个 Magic 8-Ball 游戏的 Ruby 实现。计算机会随机回答您提出的问题。请注意，注释的缩进级别与每个部分中的代码相同。

魔术球.rb

# The Eightball class represents the Magic 8-Ball.
class Eightball
  
  # Set up the available choices
  def initialize
      @choices = ["Yes", "No", "All signs point to yes", "Ask again later", "Don't bet on it"]
  end
  
  # Select a random choice from the available choices
  def shake
    @choices.sample
  end
end

def play
  puts "Ask the Magic 8 Ball your question."

  # Since we don't need their answer, we won't capture it.
  gets

  # Create a new instance of the Magic 8 Ball and use it to get an answer.
  eightball = Eightball.new
  answer = eightball.shake
  puts answer
  
  # Prompt to restart the game and evaluate the answer.
  puts "Want to try again? Press 'y' to continue or any other key to quit."
  answer = gets.chop
  
  if answer == 'y'
    play
  else
    exit
  end
end

# Start the first game.
play

评论应该帮助程序员，无论是原始程序员还是其他使用或协作项目的人。这意味着必须像代码一样维护注释。与代码相矛盾的评论比没有评论更糟糕。

当你刚开始时，你可能会写很多评论来帮助你理解你在做什么。但是随着您获得更多经验，您应该寻求使用注释来解释代码背后的 why，而不是 what 或 how。除非代码特别棘手，否则查看代码通常可以知道代码在做什么或它是如何做的。

例如，一旦你了解了 Ruby，这种评论就没有那么有用了：

# print "Hello Horld" to the screen.
print "Hello World"

这条评论重申了代码已经做了什么，虽然它不会影响程序的输出，但在您阅读代码时会产生额外的噪音。

有时您需要编写更详细的评论。这就是块评论的用途。

阻止评论

您可以使用块注释来解释更复杂的代码或您不希望读者熟悉的代码。这些较长形式的注释适用于后面的部分或全部代码，并且也与代码在同一级别缩进。

在块注释中，每一行都以井号开头，后跟一个空格以方便阅读。如果您需要使用多个段落，则应使用包含单个井号标记的行分隔它们。

这是 Sinatra web 框架源代码中的块注释示例。它为其他开发人员提供了有关此特定代码如何工作的一些上下文：

https://github.com/sinatra/sinatra/blob/master/lib/sinatra/base.rb

...
  # Some Rack handlers (Thin, Rainbows!) implement an extended body object protocol, however,
  # some middleware (namely Rack::Lint) will break it by not mirroring the methods in question.
  # This middleware will detect an extended body object and will make sure it reaches the
  # handler directly. We do this here, so our middleware and middleware set up by the app will
  # still be able to run.
  class ExtendedRack < Struct.new(:app)
    def call(env)
      result, callback = app.call(env), env['async.callback']
      return result unless callback and async?(*result)
      after_response { callback.call result }
      setup_close(env, *result)
      throw :async
    end
...

当您需要彻底解释代码片段时，块注释非常有用。但是，您应该尽量避免过度注释您的代码，因为这些注释可能是多余的并会产生额外的噪音。相信其他程序员能够理解 Ruby 代码，除非您是为特定受众编写的。注释应该添加上下文，而不是重复代码。

Ruby 有另一种用于多行注释的语法，但很少使用。这是一个例子：

多行.rb

=begin
This is a multi-line comment.
You can use this approach to make your comments
span multiple lines without placing hash marks at the start of each
line.
=end

=begin 和 =end 行必须位于行首。它们不能缩进。正是因为这个原因，你很少会看到它被使用。

接下来让我们看看内联注释。

内联评论

内联注释出现在语句的同一行，跟在代码本身之后。与其他注释一样，它们以井号开头，后跟一个空格字符以提高可读性。

通常，内联注释看起来像这样：

[code]  # Inline comment about the code

内联注释应该谨慎使用，但可以有效地解释代码中棘手或不明显的部分。如果您认为您将来可能不记得您正在编写的代码行，或者您正在与您认识的可能不熟悉代码的所有方面的人合作，它们也很有用。

例如，如果您在 Ruby 程序中不使用大量数学，您或您的合作者可能不知道以下内容创建了一个复数，因此您可能希望包含一个内联注释：

a=Complex(4,3) # Create the complex number 4+3i

您还可以使用内联注释来解释做某事的原因：

pi = 3.14159 # Intentionally limiting the value of pi for this program.

仅在必要时使用在线注释，并且它们可以为阅读程序的人提供有用的指导。

注释掉测试代码

除了使用注释来记录代码之外，您还可以使用井号来注释掉您在测试或调试当前正在创建的程序时不想执行的代码。有时，当您在添加新代码行后遇到错误时，您可能希望将其中的一些注释掉，看看您是否可以通过排除过程来解决问题。

例如，在 Magic 8-Ball 游戏中，您可能希望阻止游戏再次运行，因为您只想确保代码正确评估答案。您只需注释掉再次启动游戏的代码行：

8ball.rb

...
  
  # Prompt to restart the game and evaluate the answer.
  puts "Want to try again? Press 'y' to continue or any other key to quit."
  answer = gets.chop
  
  if answer == 'y'
    # play
  else
    exit
  end
end
...

注释还允许您在确定如何在代码中实现解决方案时尝试替代方案。例如，在 Ruby 中处理数组时，您可能想尝试几种不同的方法。您可以使用注释来测试每种方法并确定您最喜欢哪一种：

鲨鱼.rb

sharks = ["Tiger", "Great White", "Hammerhead"]

# for shark in sharks do
#  puts shark
# end

sharks.each do |shark|
  puts shark
end

注释掉代码可以让您尝试不同的编程方法，并通过系统地注释和运行程序的一部分来帮助您找到错误的根源。

结论

在您的 Ruby 程序中使用注释可以使程序对人类（包括您未来的自己）更具可读性。包含相关且有用的适当注释可以让其他人更轻松地与您在编程项目上进行协作。当您在很长一段时间后重新访问您的项目时，它们还将帮助您理解您将来编写的代码。