| blob | 00d19d588af508f9e026fd1a0080da632ac6d699 |
1 = Code Comments
3 Ruby has two types of comments: inline and block.
5 Inline comments start with the <code>#</code> character and continue until the
6 end of the line:
8 # On a separate line
9 class Foo # or at the end of the line
10 # can be indented
11 def bar
12 end
13 end
15 Block comments start with <code>=begin</code> and end with <code>=end</code>.
16 Each should start on a separate line.
18 =begin
19 This is
20 commented out
21 =end
23 class Foo
24 end
26 =begin some_tag
27 this works, too
28 =end
30 <code>=begin</code> and <code>=end</code> can not be indented, so this is a
31 syntax error:
33 class Foo
34 =begin
35 Will not work
36 =end
37 end
39 == Magic Comments
41 While comments are typically ignored by Ruby, special "magic comments" contain
42 directives that affect how the code is interpreted.
44 Top-level magic comments must appear in the first comment section of a file.
46 NOTE: Magic comments affect only the file in which they appear;
47 other files are unaffected.
49 # frozen_string_literal: true
51 var = 'hello'
52 var.frozen? # => true
54 === Alternative syntax
56 Magic comments may consist of a single directive (as in the example above).
57 Alternatively, multiple directives may appear on the same line if separated by ";"
58 and wrapped between "-*-" (see Emacs' {file variables}[https://www.gnu.org/software/emacs/manual/html_node/emacs/Specifying-File-Variables.html]).
60 # emacs-compatible; -*- coding: big5; mode: ruby; frozen_string_literal: true -*-
62 p 'hello'.frozen? # => true
63 p 'hello'.encoding # => #<Encoding:Big5>
65 === +encoding+ Directive
67 Indicates which string encoding should be used for string literals,
68 regexp literals and <code>__ENCODING__</code>:
70 # encoding: big5
72 ''.encoding # => #<Encoding:Big5>
74 Default encoding is UTF-8.
76 Top-level magic comments must start on the first line, or on the second line if
77 the first line looks like <tt>#! shebang line</tt>.
79 The word "coding" may be used instead of "encoding".
81 === +frozen_string_literal+ Directive
83 Indicates that string literals should be allocated once at parse time and frozen.
85 # frozen_string_literal: true
87 3.times do
88 p 'hello'.object_id # => prints same number
89 end
90 p 'world'.frozen? # => true
92 The default is false; this can be changed with <code>--enable=frozen-string-literal</code>.
93 Without the directive, or with <code># frozen_string_literal: false</code>,
94 the example above would print 3 different numbers and "false".
96 Starting in Ruby 3.0, string literals that are dynamic are not frozen nor reused:
98 # frozen_string_literal: true
100 p "Addition: #{2 + 2}".frozen? # => false
102 It must appear in the first comment section of a file.
104 === +warn_indent+ Directive
106 This directive can turn on detection of bad indentation for statements that follow it:
108 def foo
109 end # => no warning
111 # warn_indent: true
112 def bar
113 end # => warning: mismatched indentations at 'end' with 'def' at 6
115 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.
117 === +shareable_constant_value+ Directive
119 Note: This directive is experimental in Ruby 3.0 and may change in future releases.
121 This special directive helps to create constants that hold only immutable objects, or {Ractor-shareable}[rdoc-ref:Ractor@Shareable+and+unshareable+objects] constants.
123 The directive can specify special treatment for values assigned to constants:
125 * +none+: (default)
126 * +literal+: literals are implicitly frozen, others must be Ractor-shareable
127 * +experimental_everything+: all made shareable
128 * +experimental_copy+: copy deeply and make it shareable
130 ==== Mode +none+ (default)
132 No special treatment in this mode (as in Ruby 2.x): no automatic freezing and no checks.
134 It has always been a good idea to deep-freeze constants; Ractor makes this
135 an even better idea as only the main ractor can access non-shareable constants:
137 # shareable_constant_value: none
138 A = {foo: []}
139 A.frozen? # => false
140 Ractor.new { puts A } # => can not access non-shareable objects by non-main Ractor.
142 ==== Mode +literal+
144 In "literal" mode, constants assigned to literals will be deeply-frozen:
146 # shareable_constant_value: literal
147 X = [{foo: []}] # => same as [{foo: [].freeze}.freeze].freeze
149 Other values must be shareable:
151 # shareable_constant_value: literal
152 X = Object.new # => cannot assign unshareable object to X
154 Note that only literals directly assigned to constants, or recursively held in such literals will be frozen:
156 # shareable_constant_value: literal
157 var = [{foo: []}]
158 var.frozen? # => false (assignment was made to local variable)
159 X = var # => cannot assign unshareable object to X
161 X = Set[1, 2, {foo: []}].freeze # => cannot assign unshareable object to X
162 # (`Set[...]` is not a literal and
163 # `{foo: []}` is an argument to `Set.[]`)
165 The method Module#const_set is not affected.
167 ==== Mode +experimental_everything+
169 In this mode, all values assigned to constants are made shareable.
171 # shareable_constant_value: experimental_everything
172 FOO = Set[1, 2, {foo: []}]
173 # same as FOO = Ractor.make_sharable(...)
174 # OR same as `FOO = Set[1, 2, {foo: [].freeze}.freeze].freeze`
176 var = [{foo: []}]
177 var.frozen? # => false (assignment was made to local variable)
178 X = var # => calls `Ractor.make_shareable(var)`
179 var.frozen? # => true
181 This mode is "experimental", because it might be error prone, for
182 example by deep-freezing the constants of an external resource which
183 could cause errors:
185 # shareable_constant_value: experimental_everything
186 FOO = SomeGem::Something::FOO
187 # => deep freezes the gem's constant!
189 This will be revisited before Ruby 3.1 to either allow `everything`
190 or to instead remove this mode.
192 The method Module#const_set is not affected.
194 ==== Mode +experimental_copy+
196 In this mode, all values assigned to constants are deeply copied and
197 made shareable. It is safer mode than +experimental_everything+.
199 # shareable_constant_value: experimental_copy
200 var = [{foo: []}]
201 var.frozen? # => false (assignment was made to local variable)
202 X = var # => calls `Ractor.make_shareable(var, copy: true)`
203 var.frozen? # => false
204 Ractor.shareable?(X) #=> true
205 var.object_id == X.object_id #=> false
207 This mode is "experimental" and has not been discussed thoroughly.
208 This will be revisited before Ruby 3.1 to either allow `copy`
209 or to instead remove this mode.
211 The method Module#const_set is not affected.
213 ==== Scope
215 This directive can be used multiple times in the same file:
217 # shareable_constant_value: none
218 A = {foo: []}
219 A.frozen? # => false
220 Ractor.new { puts A } # => can not access non-shareable objects by non-main Ractor.
222 # shareable_constant_value: literal
223 B = {foo: []}
224 B.frozen? # => true
225 B[:foo].frozen? # => true
227 C = [Object.new] # => cannot assign unshareable object to C (Ractor::IsolationError)
229 D = [Object.new.freeze]
230 D.frozen? # => true
232 # shareable_constant_value: experimental_everything
233 E = Set[1, 2, Object.new]
234 E.frozen? # => true
235 E.all(&:frozen?) # => true
237 The directive affects only subsequent constants and only for the current scope:
239 module Mod
240 # shareable_constant_value: literal
241 A = [1, 2, 3]
242 module Sub
243 B = [4, 5]
244 end
245 end
247 C = [4, 5]
249 module Mod
250 D = [6]
251 end
252 p Mod::A.frozen?, Mod::Sub::B.frozen? # => true, true
253 p C.frozen?, Mod::D.frozen? # => false, false