在生物信息学应用程序中迁移，该应用程序更改列名并解释其基本原理。

Question

这段非常短的代码是一种迁移，在迁移中，列名被更改为更具描述性。它是用RoR编写的更大的生物信息学应用程序的一部分，该应用程序分析多个生物信息学工具的输出，然后将结果汇总并存储在PostgreSQL数据库中。目的是分析下一代测序数据。

我想提请大家注意评论的风格。这段代码是否遵循Ruby中关于块和行注释的常见最佳实践？在这里，块注释看起来比行注释“更干净”，但是我可能错了。例如，Rubocop标记了这些。我的主要问题是注释样式，而不是迁移的可执行代码。

=begin

Change column name to better reflect what is stored in that field.

The name orig_num_reads or num_clusters will now refer to the number
of reads or number of clusters that came off the sequencer. After
that, the upstream code may optionally do a downsampling step, which
results in delivered_num_reads. Those reads are used by Kraken for
classification, and also to store in the delivered_num_reads column in
the database. After that, there is usually another optional
downsampling step, this time in Galaxy. The resulting number of reads
is stored in num_reads column. So:

[sequencer] -> orig_num_reads
[downsample in upstream code (optional)] -> delivered_num_reads (used in Kraken)
[donsample in Galaxy (optional)] -> num_reads

=end

class RenameOrigNumReadsToDeliveredNumReads < ActiveRecord::Migration[5.2]
  def change
    rename_column :read_groups, :orig_num_reads, :delivered_num_reads
  end
end

注:我已知道以下情况：

类: RuboCop::Cop::Style::BlockComments - rubocop的文档(1.21.0)

块评论是个坏主意，Troels Henriksen著

黑客新闻:阻止评论是个坏主意

Answer 1

这段代码是否遵循Ruby中关于块和行注释的常见最佳实践？

不，它不会。

由于害怕在这里引发一场火焰大战，只要你明白自己在做什么，这也无关紧要，但如果其他遵循这些标准的开发人员发现了这些代码，他们可能会对你发火:)

就我个人而言，我更喜欢线上的评论。对于您的情况，您要对主类进行注释并不是什么大问题，但是当您开始在嵌套块中进行注释时，它会给块注释带来麻烦。

以下列代码为例：

module SomeModule
  class YourClass
    def a_method
      if true
        =begin
        a
        very
        long
        multi
        lines
        comment
        =end
        puts "Hello"
      else
        puts "Goodbye"
      end
    end
  end
end

这不是一个有效的ruby代码，它不会执行

┗ ruby your_class.rb
your_class.rb:5: syntax error, unexpected '='
      =begin
your_class.rb:7: syntax error, unexpected '=', expecting end
      =end
your_class.rb:9: else without rescue is useless
    else
your_class.rb:14: syntax error, unexpected end-of-input, expecting end

要使块注释有效，必须在行的乞讨处定义它，如下所示：

module SomeModule
  class YourClass
    def a_method
      if true
=begin
        a
        very
        long
        multi
        lines
        comment
=end
        puts "Hello"
      else
        puts "Goodbye"
      end
    end
  end
end

是的，这是你所见过的最丑陋的事情，因为你不尊重代码缩进，所以这里的选项是注释每一行：

module SomeModule
  class YourClass
    def a_method
      if true
        # a
        # very
        # long
        # multi
        # lines
        # comment
        puts "Hello"
      else
        puts "Goodbye"
      end
    end
  end
end

现在，您可能会认为这将是一个痛苦的评论每一行，但大多数IDE有选择的文本，以评论。使用VSCode，我只需按cmd + /，它就能工作，但是对于其他IDE，可能会使用相同或类似的键组合。

如果您并不真正关心这些类型的警告，那么始终可以选择禁用此规则，在项目的根文件夹中创建一个.rubocop.yml文件，如下所示：

Style/BlockComments:
  # You can disable the cop completely
  Enabled: false
  # Or exclude some specific folders/files from being inspected
  Exclude:
    - 'db/**/*'