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

. We can change this by adding either the
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


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

had been called on each of them, making the interpreter to raise a
if you happen to try to modify it.

Each new string is allocated memory in Ruby:

def test
  s = "hello world"

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"

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

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
on it. You can also freeze a mutable (unfrozen) string literal with the unary


Introduced experimentally in Ruby 3.0, this directive helps to create constants that hold only immutable objects, or

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.



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

# warn_indent: true

def comments

#=> 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

will prevent these warnings from showing.