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
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
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
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 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.