comments - Documentation for Ruby 4.0 (original) (raw)

Ruby has two types of comments: inline and block.

Inline comments start with the # character and continue until the end of the line:

class Foo

def bar end end

Block comments start with =begin and end with =end. Each should start on a separate line.

class Foo end

=begin and =end can not be indented, so this is a syntax error:

class Foo =begin Will not work =end end

While comments are typically ignored by Ruby, special “magic comments” contain directives that affect how the code is interpreted.

Top-level magic comments must appear in the first comment section of a file.

NOTE: Magic comments affect only the file in which they appear; other files are unaffected.

var = 'hello' var.frozen?

Alternative syntax

Magic comments may consist of a single directive (as in the example above). Alternatively, multiple directives may appear on the same line if separated by “;” and wrapped between “-*-” (see Emacs’ file variables).

p 'hello'.frozen? p 'hello'.encoding

encoding Directive

Indicates which string encoding should be used for string literals, regexp literals and __ENCODING__:

''.encoding

Default encoding is UTF-8.

Top-level magic comments must start on the first line, or on the second line if the first line looks like #! shebang line.

The word “coding” may be used instead of “encoding”.

frozen_string_literal Directive

Indicates that string literals should be allocated once at parse time and frozen.

3.times do p 'hello'.object_id end p 'world'.frozen?

The default is false; this can be changed with --enable=frozen-string-literal. Without the directive, or with # frozen_string_literal: false, the example above would print 3 different numbers and “false”.

Starting in Ruby 3.0, string literals that are dynamic are not frozen nor reused:

p "Addition: #{2 + 2}".frozen?

It must appear in the first comment section of a file.

warn_indent Directive

This directive can turn on detection of bad indentation for statements that follow it:

def foo end

def bar end

Another way to get these warnings to show is by running Ruby with warnings (ruby -w). Using a directive to set this false will prevent these warnings to show.

shareable_constant_value Directive

Note: This directive is experimental in Ruby 3.0 and may change in future releases.

This special directive helps to create constants that hold only immutable objects, or Ractor-shareable constants.

The directive can specify special treatment for values assigned to constants:

Mode none (default)

No special treatment in this mode (as in Ruby 2.x): no automatic freezing and no checks.

It has always been a good idea to deep-freeze constants; Ractor makes this an even better idea as only the main ractor can access non-shareable constants:

A = {foo: []} A.frozen? Ractor.new { puts A }

Mode literal

In “literal” mode, constants assigned to literals will be deeply-frozen:

X = [{foo: []}]

Other values must be shareable:

X = Object.new

Note that only literals directly assigned to constants, or recursively held in such literals will be frozen:

var = [{foo: []}] var.frozen? X = var

X = Set[1, 2, {foo: []}].freeze

The method Module#const_set is not affected.

Mode experimental_everything

In this mode, all values assigned to constants are made shareable.

FOO = Set[1, 2, {foo: []}]

var = [{foo: []}] var.frozen? X = var var.frozen?

This mode is “experimental”, because it might be error prone, for example by deep-freezing the constants of an external resource which could cause errors:

FOO = SomeGem::Something::FOO

This will be revisited before Ruby 3.1 to either allow ‘everything` or to instead remove this mode.

The method Module#const_set is not affected.

Mode experimental_copy

In this mode, all values assigned to constants are deeply copied and made shareable. It is safer mode than experimental_everything.

var = [{foo: []}] var.frozen? X = var var.frozen? Ractor.shareable?(X) var.object_id == X.object_id

This mode is “experimental” and has not been discussed thoroughly. This will be revisited before Ruby 3.1 to either allow ‘copy` or to instead remove this mode.

The method Module#const_set is not affected.

Scope

This directive can be used multiple times in the same file:

A = {foo: []} A.frozen? Ractor.new { puts A }

B = {foo: []} B.frozen? B[:foo].frozen?

C = [Object.new]

D = [Object.new.freeze] D.frozen?

E = Set[1, 2, Object.new] E.frozen? E.all(&:frozen?)

The directive affects only subsequent constants and only for the current scope:

module Mod

A = [1, 2, 3] module Sub B = [4, 5] end end

C = [4, 5]

module Mod D = [6] end p Mod::A.frozen?, Mod::Sub::B.frozen? p C.frozen?, Mod::D.frozen?