mirror of
https://github.com/carbon-language/carbon-lang.git
synced 2026-11-22 03:16:40 +00:00
Carbon currently requires a comment to be the only non-whitespace on its line. A `//` comment that follows other content on a line, called a _trailing comment_, is a lexer error. This proposal removes that restriction, allowing a comment to follow other content on a line. Everything else about comments is unchanged: a comment still begins with `//`, still requires whitespace after the `//`, and still runs to the end of the line. Carbon continues to provide only line comments; no block or intra-line comments are added. Three observations motivate the change. First, trailing comments are well suited to short _annotations_ attached to a specific entity or value on a line. Second, the lexer design now makes it trivial to lex trailing comments, and in fact requires extra logic and potentially cost to reject them. Third, C++ code routinely uses trailing comments, so allowing them lets Carbon carry the layout of migrated code over directly, rather than reworking each comment to read well in a different structure. Implementation notes (beyond the proposal's design): Keeping trailing comments cheap to lex required a few supporting changes, all of which keep the cost off the lexer's hot path: - The lexer already dispatches `//` to comment lexing wherever it appears, so classifying a comment as trailing is a single O(1) check of whether the `//` is the line's first non-whitespace (`start + indent`). The hot comment path is otherwise unchanged. - That check relies on each line's recorded indentation being its real leading whitespace. Multi-line string literals previously recorded the column where the literal opened for the lines they span; they now record the true (closing-delimiter) indentation instead. - Parser error recovery (`SkipPastLikelyEnd`) had relied on that opening-column indentation to keep tokens following a multi-line string literal attached to the same construct. It now reconstructs that relationship directly by consulting the line on which the literal opened, including when other tokens follow the closing delimiter (such as `''' + "more"`). This is on the cold recovery path. - `CommentData` records the trailing bit in the high bit of its length field, keeping it at 8 bytes. Assisted-by: Claude Code
79 lines
2.6 KiB
Markdown
79 lines
2.6 KiB
Markdown
# Comments
|
|
|
|
<!--
|
|
Part of the Carbon Language project, under the Apache License v2.0 with LLVM
|
|
Exceptions. See /LICENSE for license information.
|
|
SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
|
|
-->
|
|
|
|
<!-- toc -->
|
|
|
|
## Table of contents
|
|
|
|
- [Overview](#overview)
|
|
- [Details](#details)
|
|
- [Style](#style)
|
|
- [Alternatives considered](#alternatives-considered)
|
|
- [References](#references)
|
|
|
|
<!-- tocstop -->
|
|
|
|
## Overview
|
|
|
|
A comment is a lexical element beginning with the characters `//` and running to
|
|
the end of the line. We have no mechanism for physical line continuation, so a
|
|
trailing `\` does not extend a comment to subsequent lines.
|
|
|
|
A comment may be the entire content of a line, or it may follow other content on
|
|
the line as a _trailing comment_. A full-line comment typically introduces the
|
|
code below it, while a trailing comment annotates the content on its own line.
|
|
|
|
## Details
|
|
|
|
After the `//` a whitespace character is required to make the comment valid.
|
|
Newline is a whitespace character, so a line containing only `//` is a valid
|
|
comment. The end of the file also constitutes whitespace.
|
|
|
|
All comments are removed prior to formation of tokens; a comment produces no
|
|
token.
|
|
|
|
Example:
|
|
|
|
```
|
|
// This is a comment and is ignored. \
|
|
This is not a comment.
|
|
|
|
var Int: x; // This is a trailing comment annotating `x`.
|
|
```
|
|
|
|
Currently no support for block comments is provided. Commenting out larger
|
|
regions of human-readable text or code is accomplished by commenting out every
|
|
line in the region.
|
|
|
|
## Style
|
|
|
|
Full-line and trailing comments serve different purposes:
|
|
|
|
- Prefer a full-line comment for documentation. It has less line-length
|
|
pressure and more easily stays attached to the code it describes as that
|
|
code changes.
|
|
- Use a trailing comment only to annotate or mark a specific line, in a
|
|
context where a comment on the preceding line would be awkward, verbose, or
|
|
imprecise.
|
|
|
|
## Alternatives considered
|
|
|
|
- [Intra-line comments](/proposals/p000198-comments.md#intra-line-comments)
|
|
- [Multi-line text comments](/proposals/p000198-comments.md#multi-line-text-comments)
|
|
- [Block comments](/proposals/p000198-comments.md#block-comments-2)
|
|
- [Documentation comments](/proposals/p000198-comments.md#documentation-comments)
|
|
- [Code folding comments](/proposals/p000198-comments.md#code-folding-comments)
|
|
- [Keep requiring comments to be alone on their line](/proposals/p007441-trailing-comments.md#keep-requiring-comments-to-be-alone-on-their-line)
|
|
|
|
## References
|
|
|
|
- Proposal
|
|
[#198: Comments](https://github.com/carbon-language/carbon-lang/pull/198)
|
|
- Proposal
|
|
[#7441: Trailing comments](https://github.com/carbon-language/carbon-lang/pull/7441)
|