In Ruby 4.0, why might a file's # frozen_string_literal: true magic comment be ignored, and what syntax rules must magic comments follow?

## What a magic comment is Most comments are ignored, but a few written as `# key: value` are **directives** that change how the parser treats the file. Ruby 4.0's default parser, Prism, recognises four keys: - `encoding` (or `coding`): the source encoding of the file; - `frozen_string_literal`: how string literals in the file are allocated; - `warn_indent`: whether mismatched indentation of `end` produces warnings; - `shareable_constant_value`: how values assigned to constants are treated. What each directive *does* is a topic for its own feature. This question is about **where and how** they must be written, because a misplaced directive is silently ignored and the file then behaves differently from what its author believes. Each directive affects **only the file it appears in**, never the files that file requires. ## Where each directive must appear | Directive | Where it must appear | If it is elsewhere | |---|---|---| | `encoding` / `coding` | line 1, or line 2 when line 1 is a `#!` shebang | not treated as an encoding directive | | `frozen_string_literal` | in the comments at the top of the file, before any code | ignored; `ruby -w` warns it is ignored after any tokens | | `warn_indent` | any comment line; affects the code after it | not applicable | | `shareable_constant_value` | a comment-only line; may repeat, affecting later constants in the same scope | ignored with a verbose warning when code shares the line | ## Syntax rules the parser applies 1. **Key, colon, value.** The comment is `key: value`; spaces around the colon are fine, but `frozen_string_literal = true` has no colon and is not a directive. 2. **Flexible key spelling.** Keys are matched case-insensitively, and each `-` is treated as `_`, so `Frozen-String-Literal` matches. 3. **Boolean values.** `true` and `false` are accepted in any case. Any other value, such as `yes`, is ignored and reported as an invalid value when warnings are on. 4. **Nothing else in the comment.** In the plain form, only whitespace may follow the value; `# frozen_string_literal: true # perf` is therefore an ordinary comment. 5. **Emacs style for several directives.** Between `-*-` markers, directives are separated by `;`: `# -*- coding: utf-8; frozen_string_literal: true -*-`. ## Diagnosing an ignored directive 1. Run the file with `ruby -w`. Prism's verbose warnings catch a `frozen_string_literal` placed after code and an invalid value. 2. If there is no warning, check the spelling rules: a missing colon or trailing text produces no warning at all. 3. Check the position: a `require` line, a `module` line or any other code above the directive disables it. 4. Check the file: a directive in `app.rb` does nothing for `lib/loan.rb`; each file needs its own. 5. Confirm the effect at run time with a probe such as `p "x".frozen?` placed in the same file. ## Why the rules are strict - Prism accepts `frozen_string_literal` only before the first code token, which keeps a whole file under one setting instead of switching halfway through. - The encoding must be known before the parser can read the rest of the bytes, so it is pinned to the first line (or the line after a shebang). - Requiring the whole comment to be the directive keeps ordinary prose comments, which often contain colons, from being mistaken for directives. ## Interview summary 1. Directives live in the comments at the top of the file and apply to that file only. 2. `frozen_string_literal` must precede all code; `encoding` must be on line 1 or 2. 3. The comment is `key: value` and nothing else, or several pairs inside `-*-` markers. 4. Keys ignore case and treat dashes as underscores; boolean values must be `true` or `false`. 5. `ruby -w` reveals some mistakes, but a missing colon or trailing text is silent. ## Common setups - A shebang on line 1 followed by `# frozen_string_literal: true` on line 2 is valid. - A licence header made only of comments, and blank lines, may come first; code may not. - Linters can require the directive in every file; which files a team enforces is a tooling decision rather than a language rule.