Migration in a bioinformatics application that changes a column name and explains the rationale

Question

This very short piece of code is a migration in which a column name is changed to be more descriptive. It is part of a larger bioinformatics application written in RoR that parses the output of multiple bioinformatics tools, then summarizes and stores the results in PostgreSQL database. The goal is to analyze next generation sequencing data.

I want to call attention to the comment style. Does this code follow common best practices in Ruby regarding block vs line comments? Block comments appear "cleaner" than line comments here, but I may be wrong. For example, Rubocop flags these. My main question is about the comment style, not about the executable code of the migration.

=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

Note: I am already aware of these:
Class: RuboCop::Cop::Style::BlockComments — Documentation for rubocop (1.21.0)
Block Comments are a Bad Idea, by Troels Henriksen
Hacker News: Block Comments Are a Bad Idea

• jdt: I don't know RoR but the class name is making my eyes water =)

Answer 1

Does this code follow common best practices in Ruby regarding block vs line comments?

No, it doesn't.
And with the fear of starting a flamewar here, it doesn't matter either as long as you understand what you're doing, but if other devs that follow these standards find that code, they could get mad with you :)
Personally, I prefer line comments. For your case, where you're commenting the main class, is not a big issue, but when you start commenting in nested blocks, it gets troublesome with block comments.
Take the following code as example:

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

this is not a valid ruby code and it won't execute

┗ 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

as to make a block comment valid, it must be defined at the beggining of the line, like this:

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

and yeah, is the ugliest thing you'll ever see because you're not respecting the code indentation, so the option to this is commenting every line:

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

Now you could think this will be a pain to comment every line, but most of IDEs have the option to select the text to be commented. With VSCode I just press cmd + / and it works, but with other IDEs probably will work with the same or similar key combination.
If you don't really care about these type of warnings, there's always the option to disable this rule creating a .rubocop.yml file in your project's root folder like this:

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