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, there are some comments that are interpreted by Ruby. They are known as magic comments, or magic instructions.
# 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 magic comment’s specifications.
Let’s take a look at the implicit rules that we need to know to get the best out of this feature.
There are two syntaxes to declare a magic comment:
# encoding: UTF-8
# -*- encoding: UTF-8 -*-
Both syntaxes will be similarly interpreted by Ruby.
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 the
world.rb file is the default Ruby encoding:
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.
Here, Ruby will parse and process both magic comments — we’ll go into detail of these magic comments in the next section.
So, they’ll both be effective in this file.
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.
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
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.
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.
Here, only the first declared
encoding: instruction is processed. The others are skipped.
Note that we can use
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.
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.
Here, only the last declared
warn_indent: instruction is processed. The others are skipped.
Thank you for taking the time to read this piece.