Magic Comments in Ruby

An overview of magic comments and the precedence rules applied to them

Mehdi Farsi
Aug 13, 2019 · 3 min read
Image for post
Image for post

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, there are some comments that 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 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.

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: UTF-8.

So, the magic comment doesn’t have any impact on the required files.

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

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.

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

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.

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.

Voilà!

Thank you for taking the time to read this piece.

RubyCademy

E-Learning platform for Ruby and Ruby on Rails

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store