In Ruby, how do =begin and =end create a multi-line comment, and why do most Rubyists use consecutive # lines instead?

## Two ways to comment Ruby recognises two comment syntaxes, and both are ignored by the interpreter. | Form | Starts with | Ends at | Can be indented? | |---|---|---|---| | inline comment | `#` | the end of the line | yes | | block comment (embedded document) | a line beginning `=begin` | a line beginning `=end` | no | ## Inline comments with # - A `#` outside a string or regexp literal starts a comment that runs to the end of the line. - It can sit on its own line, at any indentation, or after code: `renew! # raises at the limit`. - Several consecutive `#` lines form a multi-line comment, which is how nearly all Ruby code writes one. - A `#` **inside a string** is ordinary text: `puts "Shelf #3" # restock` prints `Shelf #3`. ## Block comments with =begin and =end The rules are strict: 1. `=begin` must be at the very start of a line, with no leading spaces. 2. `=end` must also start at column 0, on its own line. 3. Everything between them is ignored, including lines that look like code. 4. Text may follow `=begin` on the same line (`=begin notes`), and it is ignored too. 5. If the file ends before `=end`, parsing fails with `embedded document meets end of file`. Rule 1 is the practical problem. Code inside a class or method is indented, so commenting out part of a method with `=begin` requires pulling the markers back to column 0: ```ruby class LibraryLoan def fine =begin old_rate * days_overdue =end 0 end end ``` Indenting the markers to match the code (` =begin`) makes the whole file a `SyntaxError`. ## Why # lines win - **Indentation**: `#` lines follow the code's indentation, so the file keeps its shape. - **Editor support**: every Ruby-aware editor comments and uncomments a selection by adding or removing `#`. - **Visibility**: each commented line is marked, so a reader scrolling through a long block never mistakes it for live code. - **Linting**: community style guides and linters prefer `#` and flag block comments. - **Documentation tools** read the `#` comments directly above a method or class, so the everyday form is also the documented one. ## Things that look like comments but are not - **Magic comments** such as `# frozen_string_literal: true` are written with `#`, but the parser reads them as directives when they appear in the right place at the top of a file. - **`__END__`** on a line by itself ends the program source: nothing after it is parsed, so it cannot comment out code in the middle of a file. - **A shebang line** (`#!/usr/bin/env ruby`) is a `#` comment to the parser; the operating system uses it to pick the interpreter, and the `ruby` command also reads any options written on it. ## How the question is usually asked - **"Does Ruby have multi-line comments?"** Yes, `=begin`/`=end`, with the column-0 rule; in practice consecutive `#` lines. - **"Why does this file fail after I added =begin?"** The marker was indented, or `=end` is missing and the parser reached the end of the file. - **"Is `#` inside a string a comment?"** No; only a `#` outside string and regexp literals starts one. - **"What is the first line `#!/usr/bin/env ruby`?"** A shebang: a comment to the parser, an instruction to the operating system when the file is executed directly. A candidate who answers the first question with only `=begin` and never mentions `#` lines usually has not read much real Ruby code. ## In practice Reach for `#` lines by default. `=begin`/`=end` is legal and occasionally seen at the top of old scripts, but in modern code it mostly appears in interview questions about Ruby's syntax. Commented-out code itself is better deleted, since version control keeps the history.