path: root/doc/syntax/comments.rdoc

= Code Comments

Ruby has two types of comments: inline and block.

Inline comments start with the <code>#</code> character and continue until the
end of the line:

  # On a separate line
  class Foo # or at the end of the line
    # can be indented
    def bar
    end
  end

Block comments start with <code>=begin</code> and end with <code>=end</code>.
Each should start on a separate line.

  =begin
  This is
  commented out
  =end

  class Foo
  end

  =begin some_tag
  this works, too
  =end

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

  class Foo
    =begin
    Will not work
    =end
  end

== Magic Comments

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

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

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

  # frozen_string_literal: true

  var = 'hello'
  var.frozen? # => true

=== 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}[https://www.gnu.org/software/emacs/manual/html_node/emacs/Specifying-File-Variables.html]).

  # emacs-compatible; -*- coding: big5; mode: ruby -*-

  p 'hello'.frozen? # => true
  p 'hello'.encoding # => #<Encoding:Big5>

=== +encoding+ Directive

Indicates which string encoding should be used for string literals,
regexp literals and <code>__ENCODING__</code>:

  # encoding: big5

  ''.encoding # => #<Encoding:Big5>

Default encoding is UTF-8.

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

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.

  # frozen_string_literal: true

  3.times do
    p 'hello'.object_id # => prints same number
  end
  p 'world'.frozen? # => true

The default is false; this can be changed with <code>--enable=frozen-string-literal</code>.
Without the directive, or with <code># frozen_string_literal: false</code>,
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:

  # frozen_string_literal: true

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

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 # => no warning

  # warn_indent: true
  def bar
    end # => warning: mismatched indentations at 'end' with 'def' at 6

Another way to get these warnings to show is by running Ruby with warnings (<code>ruby -w</code>). 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}[rdoc-ref:Ractor@Shareable+and+unshareable+objects] constants.

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

* +none+: (default)
* +literal+: literals are implicitly frozen, others must be Ractor-shareable
* +experimental_everything+: all made shareable
* +experimental_copy+: copy deeply and make it shareable

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

  # shareable_constant_value: none
  A = {foo: []}
  A.frozen? # => false
  Ractor.new { puts A } # => can not access non-shareable objects by non-main Ractor.

==== Mode +literal+

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

  # shareable_constant_value: literal
  X = [{foo: []}] # => same as [{foo: [].freeze}.freeze].freeze

Other values must be shareable:

  # shareable_constant_value: literal
  X = Object.new # => cannot assign unshareable object to X

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

  # shareable_constant_value: literal
  var = [{foo: []}]
  var.frozen? # => false (assignment was made to local variable)
  X = var # => cannot assign unshareable object to X

  X = Set[1, 2, {foo: []}].freeze # => cannot assign unshareable object to X
                                  # (`Set[...]` is not a literal and
                                  # `{foo: []}` is an argument to `Set.[]`)

The method Module#const_set is not affected.

==== Mode +experimental_everything+

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

  # shareable_constant_value: experimental_everything
  FOO = Set[1, 2, {foo: []}]
  # same as FOO = Ractor.make_sharable(...)
  # OR same as `FOO = Set[1, 2, {foo: [].freeze}.freeze].freeze`

  var = [{foo: []}]
  var.frozen? # => false (assignment was made to local variable)
  X = var # => calls `Ractor.make_shareable(var)`
  var.frozen? # => true

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:

  # shareable_constant_value: experimental_everything
  FOO = SomeGem::Something::FOO
  # => deep freezes the gem's constant!

We will revisit to consider removing "experimental_" or removing this 
mode by checking usages before Ruby 3.1.

The method Module#const_set is not affected.

==== Mode +experimental_copy+

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

  # shareable_constant_value: experimental_everything
  var = [{foo: []}]
  var.frozen? # => false (assignment was made to local variable)
  X = var # => calls `Ractor.make_shareable(var, copy: true)`
  var.frozen? # => false
  Ractor.shareable?(X) #=> true
  var.object_id == X.object_id #=> false

This mode is "experimental", because it is not discussed enough.
We will revisit to consider removing "experimental_" or removing this 
mode by checking usages before Ruby 3.1.

The method Module#const_set is not affected.

==== Scope

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

  # shareable_constant_value: none
  A = {foo: []}
  A.frozen? # => false
  Ractor.new { puts A } # => can not access non-shareable objects by non-main Ractor.

  # shareable_constant_value: literal
  B = {foo: []}
  B.frozen? # => true
  B[:foo].frozen? # => true

  C = [Object.new] # => cannot assign unshareable object to C (Ractor::Error)

  D = [Object.new.freeze]
  D.frozen? # => true

  # shareable_constant_value: experimental_everything
  E = Set[1, 2, Object.new]
  E.frozen? # => true
  E.all(&:frozen?) # => true

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

  module Mod
    # shareable_constant_value: literal
    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? # => true, true
  p C.frozen?, Mod::D.frozen? # => false, false