3
\$\begingroup\$

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

\$\endgroup\$
1
  • 1
    \$\begingroup\$ I don't know RoR but the class name is making my eyes water =) \$\endgroup\$
    – jdt
    Sep 24, 2021 at 15:30

1 Answer 1

1
+50
\$\begingroup\$

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/**/*'  
\$\endgroup\$
1
  • 1
    \$\begingroup\$ Thank you very much for a thoughtful and detailed answer! +50. \$\endgroup\$ Oct 5, 2021 at 15:13

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.