RubyCademy
Published in

RubyCademy

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

Before to start

Please allow me to introduce here the platform that helped me to learn a big part of my knowledge about Ruby. Indeed, Pluralsight is an amazing platform.

With 50+ courses that cover various topics on Ruby and Ruby on Rails, it’s the best way to take your knowledge to the next level!

Try it for free 👇😉

Thank you for your time!

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.

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 the world.rb file 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 of 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.

Voilà!

Thank you for taking the time to read this piece.

--

--

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