Chandler Carruth
f0848b1f5e
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
Docs
This directory contains current, accepted documentation underpinning Carbon. These documents cover all aspects of Carbon ranging from the project down to detailed designs for specific language features.
If you're trying to learn more about Carbon, we recommend starting at
/README.md.
Design
Carbon language's design and rationale are documented in the
design/ directory. This documentation is intended to
support the following audiences:
- People who wish to determine whether Carbon would be the right choice for a project compared to other existing languages.
- People working on the evolution of the Carbon language who wish to understand the rationale and motivation for existing design decisions.
- People working on a specification or implementation of the Carbon language who need a detailed understanding of the intended design.
- People writing Carbon code who wish to understand why the language rules are the way they are.
This is in contrast to proposals, which document the individual decisions that led to this design (along with other changes to the Carbon project), including the rationale and alternatives considered.
Project
The project/ directory contains project-related
documentation for Carbon, including:
- goals, and the principles and roadmap derived from those goals,
- how the project works, and
- how to contribute.
Guides
The guides/ directory contains to-be-written end-user
documentation for developers writing programs in Carbon.
Spec
The spec/ directory contains the to-be-written formal
specification of the Carbon language. This is for implementers of compilers or
other tooling. This is intended to complement the toolchain.