2 min read

magic comments in ruby

Syed Aslam •

We all know and use comments in code. Every language provides a way to annotate and comment the code to provide better context to the reader of the code. These comments are typically ignored by the compiler.

In Ruby, the comments start with the # character. The text after the # character is not interpreted by the compiler and is ignored.

# This is a comment

While comments are typically ignored by Ruby, special “magic comments” contain directives that affect how the code is interpreted. Top-level magic comments must start on the first line, or on the second line if the first line looks like #! shebang line. Magic comments affect only the file in which they appear and other files are unaffected.

Magic comments defined in Ruby

coding / encoding

In Ruby, the default encoding is UTF-8. We can change this by adding either the coding: or encoding: magic comment at the top of the file. Note that this must appear in the first comment section of the file.

# encoding: stateless-iso-2022-jp-kddi

frozen_string_literal

Ruby 2.3 introduced the ability to make all string literals frozen by default. This magic comment makes all string literals in the file implicitly frozen, as if #freeze had been called on each of them, making the interpreter to raise a RuntimeError if you happen to try to modify it.

Each new string is allocated memory in Ruby:

def test
  s = "hello world"
  s.object_id
end

p test #=> 260
p test #=> 280

By setting this comment, Ruby allocates space for a given string only once improving performance and also saving time in garbage collection:

# frozen_string_literal: true

def test
  s = "hello world"
  s.object_id
end

p test #=> 260
p test #=> 260

Note that in Rubies >= 2.3 you can enable frozen string literals at a global level by passing the compiler flag --enable=frozen-string-literal that is however overridable at a file level by this magic comment. You can also override this setting regardless of global or file-level setting by prefixing the unary operator + to the string literal or by calling .dup on it. You can also freeze a mutable (unfrozen) string literal with the unary - operator.

shareable_constant_value

Introduced experimentally in Ruby 3.0, this directive helps to create constants that hold only immutable objects, or Ractor-shareable constants. It can take one these four values:

  • none: (default) no special treatment in this mode (as in Ruby 2.x): no automatic freezing and no checks
  • literal: constants assigned to literals will be deeply-frozen
  • experimental_everywhere: all values assigned to constants are made shareable (frozen). this mode is “experimental”, because it might be error prone
  • experimental_copy: freezes everything assigned to constants. the deeply copied and made shareable, "dynamic" objects will be copied so the originally referenced object will not get frozen

This directive can be used multiple times in the same file as it affects only subsequent constants and only for the current scope.

See Ruby Documentation for more information.

warn_indent

The warn_indent magic comment will show a warning whenever your indendation is wrong. The last declared warn_indent: takes precedence.

# warn_indent: true

def comments
  end

#=> warning: mismatched indentations at 'end' with 'def' at 3

Another way to get these warnings to show is by running Ruby with warnings (ruby -w). Using a directive to set this to false will prevent these warnings from showing.