Magic Comments in Ruby
An overview of magic comments and the precedence rules applied to them
In this piece, we’re going to explore the following topics:
- Comments vs. magic comments
- Specifications
- Existing magic comments
Comments vs. Magic Comments
In Ruby, you can annotate and document your code using comments.
To declare a comment we use the # character followed by our comment
Here, all the text after the # is not interpreted by Ruby. It only helps the developer to understand the code.
On the other hand, some comments are interpreted by Ruby. They are known as magic comments or magic instructions.
Here, the # encoding: big5 is interpreted by Ruby.
When Ruby reads this magic comment it automatically sets the encoding of any string declared in this file to Encoding:Big5 — we’ll dive deeper into encoding: in the last section of this article.
Now that we know the difference between a comment and a magic comment, let’s have a quick look at the magic comment’s specifications.
Specifications
Let’s take a look at the implicit rules that we need to know to get the best out of this feature.
Syntaxes
There are two syntaxes to declare a magic comment:
# encoding: UTF-8
# -*- encoding: UTF-8 -*-Both syntaxes will be similarly interpreted by Ruby.
Multiple files
Let’s see what the scope is of a magic comment.
As we can see, the magic comment is only effective in the file where it is declared. Indeed, the encoding within world.rb is the default Ruby encoding: UTF-8.
So, the magic comment doesn’t have any impact on the required files.
Multiple magic comments
We can declare multiple magic comments in the same file.
For example:
Here, Ruby will parse and process both magic comments — we’ll go into detail about these magic comments in the next section.
So, they’ll both be effective in this file.
Precedence
As precedence rules are different for each magic comment, I’ll describe these rules under each of the magic comment sections.
Now that we’re more familiar with the notion of magic comments, let’s have a look at the different magic comments we can play with.
Magic Comments
In this section, we’re going to talk about each of the magic comments. We won’t deep dive into each notion.
The goal here is to present you with the magic comments and give you the precedence rules that are applied to them. I invite you to browse the official documentation for further information, edge cases, etc.
The encoding: magic comment
In Ruby, the default encoding for any string literal is UTF-8.
Feel free to read The Evolution of Ruby Strings from 1.8 to 2.5 if you’re not familiar with the notion of codepoint and encoding.
The encoding: magic comment allows us to modify this default encoding in the file where this comment is defined.
We can see that our string encoding is Encoding:Big5 — as declared in the magic comment.
Precedence
Here, only the first declared encoding: instruction is processed. The others are skipped.
Note that we can use encoding: or coding:.
The frozen_string_literal: magic comment
This magic comment is pretty useful when you declare a similar string several times using string literals.
Indeed, it makes an optimization by only creating one object per string, based on content.
Here, we can see that if we declare two similar strings, only one instance of the String class will be created for both of them. This mechanism is especially useful when we use strings as identifiers for resources, similar to a symbol.
Precedence
Here, only the last declared frozen_string_literal: instruction is processed. The others are skipped.
The warn_indent: magic comment
This comment works the same as the ruby -w warn_indent.rb command line outputs.
$> ruby warn_indent.rb
warn_indent.rb:4: warn: mismatched indentations at 'end' with 'def'Here, we can see that if the code isn’t well-indented, Ruby raises a warning accordingly.
Precedence
Here, only the last declared warn_indent: instruction is processed. The others are skipped.
The shareable_constant_value magic comment
This directive has been released with Ruby 3. It is highly correlated to Ractor, the library that provides thread-safe parallel execution.
We will soon cover Ractor, and the shareable_constant_value magic comment in depth on the RubyCademy platform.
Ruby Mastery
We’re currently finalizing our first online course: Ruby Mastery.
Join the list for an exclusive release alert! 🔔
Also, you can follow us on x.com as we’re very active on this platform. Indeed, we post elaborate code examples every day.
💚
