Say No to Boilerplate Comments

In general, I do not believe in comments in code as they:

• add programmer effort to interpret.
• can become outdated quickly.
• indicate a bigger problem with the programmer or implementation.

original post

Whenever I come across a production Ruby on Rails app and see the original boilerplate comments such as in: config/initializers/application_controller_renderer.rb

# Be sure to restart your server when you modify this file.

# ActiveSupport::Reloader.to_prepare do
#   ApplicationController.renderer.defaults.merge!(
#     http_host: 'example.org',
#     https: false
#   )
# end

I really have to wonder: what is so important about Ruby on Rails’ default comments that they have to exist… even when they are essentially… useless!

• When upgrading the projects’ Rails version, are comments also upgraded to the latest version?? Think about this.

• Are the default comments so important that they must exist in the project and source code repository the whole time or things will fail? Remember, this is a code comment.

• Do the comments only ever exist once and if they are not saved, they disappear forever? Like photos on a certain ephmeral social service? No, just run $ rails new default_comments and tada, you have the original comments!

• I also have to argue, the comment was not written by anyone on the current team. If you have questions on how to interpret the comment, how do you do that?

So these comments’ existence on production applications perplexes me. Why are the original comments in a Ruby on Rails project exist after the projects’ deployed to production?

There’s probably any number of reasons: we wanted to move fast, we didn’t know the app would take off, the comments are everywhere, it’s already working in production.

Solution

Whatever the reason, there’s a solution: the below script on github removes all the comments from a Ruby on Rails 5.2.0 project:

class String
  def is_comment?
    line = self.lstrip.downcase

    is_ruby_comment?(line) || is_js_comment?(line)
  end

  private

  def is_ruby_comment?(line)
    line.start_with?('#')                    &&
    !line.start_with?('#!')                  &&
    !line.start_with?('#=')                  &&
    !line.include?('coding:')                &&
    !line.include?('frozen_string_literal:') &&
    !line.include?('warn_indent:')
  end

  def is_js_comment?(line)
    line.start_with?('//') &&
    !line.start_with?('//=')
  end
end

RUBY_FILE_ENDINGS = ['.rb', 'Gemfile', 'Rakefile', '.yml', '.ru']
SKIPPABLE_DIRS    = ['/tmp/', '/node_modules/', '/vendor/', '/log/', '/db/', '/lib/', '/public/']

root_dir = Dir.chdir(ARGV[0]) { Dir.glob("**/*").map {|path| File.expand_path(path) } }

root_dir.each do |file|
  next if SKIPPABLE_DIRS.any? { |skippable_dir| file.include?(skippable_dir) }

  if RUBY_FILE_ENDINGS.any? { |ruby_ending| file.end_with?(ruby_ending) } || file.end_with?('.js')
    if File.readlines(file).any? { |line| line.is_comment? }
      text_without_comments = File.readlines(file).select { |line| !line.is_comment? }.join
      reformatted_text = text_without_comments.strip.gsub(/\n{3,}/, "\n\n").gsub(/\n{2,}end/, "\nend").gsub("\n\n  ", "\n  ")
      reformatted_text = reformatted_text.gsub("port        ENV", "port ENV")
      
      File.open(file, 'w') { |file| file << reformatted_text }
    end
  end
end

Source

I haven’t tested it out yet, but it’s an automated solution to removing boilerplate comments!

Conclusion

Honestly, just delete unnecessary comments, especially boilerplate comments generated by the framework. Boilerplate comments are generally bad as they:

• are never upgraded for the app, even when upgrading the underlying framework.
• do not contribute to anything in the actual code base.
• easily generated again by using the framework to create a new project.
• were never written by anyone on the team!

If you want to remove Ruby on Rails’ boilerplate comment from your production application in an automated fashion, try Matias’ skip_rails_comments!.

Thanks Matias!