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.
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
class RenameOrigNumReadsToDeliveredNumReads < ActiveRecord::Migration[5.2]
rename_column :read_groups, :orig_num_reads, :delivered_num_reads
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