An incomplete, early, and in-progress overview of the language design. #83

jonmeow · 2020-06-17T19:22:13Z

Co-authored by: chandlerc

This proposal should be considered a starting point of the language design. It's not intended to be final; language details may change. This is intended to offer a reasonable starting point for:

Example code.
Conceptualizing Carbon at a high level.
Reasonable, but not necessarily final, approaches to features in README.md.
- If any idea is obviously bad, we can clean it up here.

This proposal is not intended to achieve:

A whole language design.
- This is way too much work for a single proposal; this is a skeletal framework only.
- As we work on feature-specific designs, we may decide to use other approaches. That's fine: we only need somewhere to start.
- The summaries in README.md may be expected to change over time.
Feature-specific files aren't intended to be well-written or comprehensive. They are a quick jot of prior thoughts.
- We want to avoid getting stuck on language details that we should consider
  more carefully regardless. If you're passionate about a feature, please feel
  free to start a new proposal for it.
- Each and every aspect of the suggested overview should be subject to careful
  examination and justification before it becomes a settled plan of record.

Chandler started this with #22. I've taken it over with the following changes:

More of a directory hierarchy.
Trying to thin out the main file (now README.md) to lighter summaries of features.
Details/rationale/alternatives should be in feature-specific files.
- Draft files are linked as references where added.

For an example of how we may proceed with feature-specific designs, see #80. In this structure:

docs/design/README.md mentions interoperability, with a light overview.
- The light overview is not yet in Carbon <-> C/C++ interoperability #80.
docs/design/interoperability/README.md goes into more depth on interoperability, covering key points of the approach.
Individual files in docs/design/interoperability/* go into more depth on interoperability.

Simple designs may not have a subdirectory. All current feature-specific designs do not -- they may be moved later.

Move firebase support into a src directory. (#15)

This is basically a snapshot of an in-progress document, moved to markdown and prepared for sharing with the wider community. It isn't finished. It isn't even necessarily up to date with the latest thinking on any particular area. But I think it will make more sense to land it as essentially a collective WIP and let people iterate on any given section as those details get sorted out. Even in its current form, I think it still provides a starting point and gives people the feel of what this will look like. There are a number of document links lost in this conversion. I've carefully left a `TODO` in the document at each point to come back and add the appropriate link back to the document once the rest of the existing material is somewhere visible. These were all fairly easy to preserve as they primarily were links out to an entire document.

Update fork

Merge

Co-authored-by: Jon Meow <46229924+jonmeow@users.noreply.github.com> Co-authored-by: josh11b <josh11b@users.noreply.github.com>

Merge

googlebot · 2020-06-17T19:22:22Z

All (the pull request submitter and all commit authors) CLAs are signed, but one or more commits were authored or co-authored by someone other than the pull request submitter.

We need to confirm that all authors are ok with their commits being contributed to this project. Please have them confirm that by leaving a comment that contains only @googlebot I consent. in this pull request.

Note to project maintainer: There may be cases where the author cannot leave a comment, or the comment is not properly detected as consent. In those cases, you can manually confirm consent of the commit author(s), and set the cla label to yes (if enabled on your project).

ℹ️ Googlers: Go here for more info.

docs/design/aliasing.md

proposals/p0083.md

jonmeow

Mostly addressing comments from @josh11b, with one from @zygoloid

jonmeow · 2020-07-10T20:45:29Z

docs/design/README.md

+  supported.
+- Line comments look like `// ...`. However, they are required to be the only
+  non-whitespace on the line for readability.
+- Block comments begin with `//\{`, and end with `//\}`. The begin and end


Trying to guess at what you mean, rephrased the next sentence.

jonmeow · 2020-07-10T20:52:39Z

docs/design/metaprogramming.md

+
+Carbon provides metaprogramming facilities that look similar to regular Carbon
+code. These are structured, and do not offer inclusion or arbitrary
+preprocessing of source text such as C/C++ does.


Yes, that's a related proposal. Note though, I'm generally not taking time to link to related proposals -- I think the right thing to do is to maybe mention them if needed elsewhere, but not in the actual design. Rather, it should be accepted that the design will evolve over time, and that the specific proposal to do that may change (e.g., due to evolving ideas, or changes in ownership like how I took this proposal from Chandler).

jonmeow · 2020-07-10T21:09:10Z

docs/design/README.md

+- `UpperCamelCase` for names of compile-time resolved constants, such that they
+  can participate in the type system and type checking of the program.


jonmeow · 2020-07-10T21:10:24Z

docs/design/README.md

+Common types that we expect to be used universally will be provided for every
+file, including `Int` and `Bool`. These will likely be defined in a `Carbon`
+package, and be treated as if always imported and aliased by every file.


Removed Carbon name.

jonmeow · 2020-07-10T21:11:32Z

docs/design/README.md

+  - Bitwise: `2 & 3`, `2 | 4`, `3 ^ 1`, `~7`
+  - Bit sequence: `1 << 3`, `8 >> 1`
+  - Comparison: `2 == 2`, `3 != 4`, `5 < 6`, `7 > 6`, `8 <= 8`, `8 >= 8`
+  - Logical: `a && b`, `c || d`


Checking with @zygoloid for a second opinion; I'd actually thought the leaning was the stated way. Of course, this is a fairly minor point and can always be swapped later if proposals change.

jonmeow · 2020-07-10T21:36:49Z

docs/design/tuples.md

+### Indices as compile-time constants
+
+In the example `t1[2, 1, 0]`, we will likely want to restrict these indices to
+compile-time constants. Without that, run-time indexing would need to suddenly
+switch to a variant-style return type to handle heterogeneous tuples. This would
+both be surprising and complex for little or no value.


jonmeow · 2020-07-10T21:39:30Z

docs/design/tuples.md

+### Multiple indices
+
+In the example `t1[2, 1, 0]`, using multiple indices in this way is a bit
+questionable. If we end up wanting to support multidimensional arrays / slices
+(a likely selling point for the scientific world), a sequence of indices seems a
+likely desired facility there. We'd either need to find a different syntax
+there, change this syntax, or cope with tuples and arrays having different
+semantics for multiple indices (which seems really bad).


Just removing this (if the final design wants to talk about this more, that's fine)

docs/design/tuples.md

jonmeow · 2020-07-10T21:45:24Z

docs/design/types.md

+# TODO
+
+<!--
+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
+-->
+
+## Table of contents
+
+<!-- toc -->
+
+- [TODO](#todo)
+- [Overview](#overview)
+
+<!-- tocstop -->
+
+## TODO
+
+This is a skeletal design, added to support [the overview](README.md). It should
+not be treated as accepted by the core team; rather, it is a placeholder until
+we have more time to examine this detail. Please feel welcome to rewrite and
+update as appropriate.
+
+## Overview


My mistake, removed

jonmeow · 2020-07-10T21:48:13Z

docs/design/variables.md

+### Declaring constants
+
+An open question is what syntax (and mechanism) to use for declaring constants.
+There are serious problems with the use of `const` in C++ as part of the type
+system, so alternatives to pseudo-types (type qualifiers) are being explored.
+The obvious syntax is `let` from Swift, although there are some questions around
+how intuitive it is for this to introduce a constant. Another candidate is `val`
+from Kotlin. Another thing we need to contend with is the surprise of const and
+reference (semantic) types.


Done, adjusted the argument for alternatives.

brycelelbach · 2020-07-15T00:33:31Z

docs/design/README.md

+- All source code is UTF-8 encoded text. For simplicity, no other encoding is
+  supported.
+- Line comments look like `// ...`. However, they are required to be the only
+  non-whitespace on the line for readability.


It makes me sad to not have the ability to write:

var Int: x = foo; // This is a variable declaration

I'm not sure I understand the rationale here.

@chandlerc I think this is from you. I personally agree with Bryce here.

I believe this reflects the current proposal of #17. Rather than injecting a personal opinion on this issue, I think that:

This can be resolved on the syntax-specific proposal, given there are differing opinions about the issue.

If we start allowing examples to use <code> // <comment>, that's more expensive to fix later if the decision is to not allow that syntax than if we assume it will not be allowed and change our minds later.

I commented there: #17 (comment)

If I could remove all end-of-line comments from my codbase, I'd be real happy. Because under maintenance, lines often get longer. Some codebases have max-column limits. And when you have to automatically re-wrap as a result, there aren't good options.

josh11b · 2020-07-16T19:52:20Z

docs/design/README.md

+- Block comments begin with `//\{`, and end with `//\}`. The begin and end
+  markers must be the only things on their lines.


Suggested change

- Block comments begin with `//\{`, and end with `//\}`. The begin and end

markers must be the only things on their lines.

- Block comments begin with a line starting with `//\{`, and end with a line starting with `//\}`.

My concern is this is difficult to read. Rewrote this a little, and gave an example.

josh11b · 2020-07-16T19:58:04Z

docs/design/README.md

+- All source code is UTF-8 encoded text. For simplicity, no other encoding is
+  supported.
+- Line comments look like `// ...`. However, they are required to be the only
+  non-whitespace on the line for readability.


@chandlerc I think this is from you. I personally agree with Bryce here.

josh11b · 2020-07-16T19:59:11Z

docs/design/README.md

+- Block comments begin with `//\{`, and end with `//\}`. They are always at the
+  start of a line.


Suggested change

- Block comments begin with `//\{`, and end with `//\}`. They are always at the

start of a line.

- Block comments begin with a line starting with `//\{`, and end with a line starting with `//\}`.

"begin with a line starting with" phrasing is a little confusing to me.

As I understand @zygoloid 's lexing proposal, there may be additional characters on the line that starts with //\{ or //\}, as in:

//\{ disabled This is disabled //\} disabled

Rewritten with example

josh11b · 2020-07-16T20:00:30Z

docs/design/metaprogramming.md

+
+Carbon provides metaprogramming facilities that look similar to regular Carbon
+code. These are structured, and do not offer inclusion or arbitrary
+preprocessing of source text such as C/C++ does.


In 4 other cases you linked to the PR, I'm not sure what is different here.

docs/design/name_lookup.md

josh11b · 2020-07-24T23:44:53Z

docs/design/README.md

+modifying other types. They also have semantics that are defined from first
+principles rather than in terms of other operations. Even though these are
+special, their names are not keywords or reserved; they are just names in the
+global scope.


Here is an example of using the phrase "global scope". I think this is consistent with how that term is used in other in-progress design docs.

Rewrote as prelude

josh11b · 2020-07-24T23:52:51Z

docs/design/README.md

+- `Baz()` is invoked if `x` is greater than `77`.
+- Nothing happens if `x` is between `42` and `77`.
+
+#### `loop`, `break`, and `continue`


I think we should replace loop with while in this section. There is no reason to be different from what people expect here.

docs/design/README.md

josh11b · 2020-07-25T17:38:59Z

docs/design/README.md

+
+Common types that we expect to be used universally will be provided for every
+file, including `Int` and `Bool`. These will likely be defined in a special
+"prelude" package which is treated as if always imported and aliased by every


I don't know what "imported and aliased" means. I think this might be another place where it would be clearer to explain that the prelude (and only the prelude) populates the global namespace.

josh11b · 2020-07-25T17:48:18Z

docs/design/naming_conventions.md

+- `UpperCamelCase` for names of compile-time resolved constants, such that they
+  can participate in the type system and type checking of the program.


See revised correction.

josh11b · 2020-07-25T17:49:55Z

docs/design/primitive_types.md

+modifying other types. They also have semantics that are defined from first
+principles rather than in terms of other operations. Even though these are
+special, their names are not keywords or reserved; they are just names in the
+implicit "prelude" that is imported and aliased into all files.


Again I don't think "imported and aliased" is clear.

Copy-pasted new text from readme

josh11b · 2020-07-25T18:07:48Z

docs/design/README.md

+- All source code is UTF-8 encoded text. For simplicity, no other encoding is
+  supported.
+- Line comments look like `// ...`. However, they are required to be the only
+  non-whitespace on the line for readability.


I commented there: #17 (comment)

jonmeow · 2020-07-27T23:05:25Z

@josh11b I started accepting changes, and then I realized I shouldn't because the decision is already underway. I can't make any more edits without an explicit decision from the core team. I agree the wording could be improved, but in the future, could you please consider filing an issue, plan out a follow-up PR for changes, or state explicit edits as a condition for your approval? This came up before with the goals PR, where I filed #106, but it's difficult to respond appropriately.

jonmeow

Comment pass; may need to take a closer look for unresponded comments

jonmeow · 2020-07-28T18:06:07Z

docs/design/README.md

+- Block comments begin with `//\{`, and end with `//\}`. The begin and end
+  markers must be the only things on their lines.


My concern is this is difficult to read. Rewrote this a little, and gave an example.

jonmeow · 2020-07-28T18:08:49Z

docs/design/README.md

+- `UpperCamelCase` for names of compile-time resolved constants, such that they
+  can participate in the type system and type checking of the program.


Thank you for suggesting a fix! I hadn't understood your criticism, so the positive example really helps.

jonmeow · 2020-07-28T18:10:38Z

docs/design/README.md

+- `Baz()` is invoked if `x` is greater than `77`.
+- Nothing happens if `x` is between `42` and `77`.
+
+#### `loop`, `break`, and `continue`


jonmeow · 2020-07-28T18:10:50Z

docs/design/README.md

+modifying other types. They also have semantics that are defined from first
+principles rather than in terms of other operations. Even though these are
+special, their names are not keywords or reserved; they are just names in the
+global scope.


Rewrote as prelude

jonmeow · 2020-07-28T18:12:18Z

docs/design/README.md

+> **TODO:** References need to be evolved.
+
+User-defined types may have template parameters. The resulting type-function may
+be used to instantiate the parameterized definition with the provided arguments


I think we'll need to switch terminology if we substantively change the meaning of "instantiate" -- it's too well known a term. As-is, I think either the templates proposal or the proposed glossary would be better places to define terminology.

jonmeow · 2020-07-28T18:13:56Z

docs/design/README.md

+>
+> **TODO:** References need to be evolved.
+
+Both implicit and explicit function parameters in Carbon can be marked as


I was looking at rewriting this, but nothing was popping out for me. For now, I'd rather rely on existing knowledge of implicit/explicit.

docs/design/name_lookup.md

jonmeow · 2020-07-28T18:19:05Z

docs/design/naming_conventions.md

+- `UpperCamelCase` for names of compile-time resolved constants, such that they
+  can participate in the type system and type checking of the program.


Accepted, thanks.

jonmeow · 2020-07-28T18:21:31Z

docs/design/primitive_types.md

+modifying other types. They also have semantics that are defined from first
+principles rather than in terms of other operations. Even though these are
+special, their names are not keywords or reserved; they are just names in the
+implicit "prelude" that is imported and aliased into all files.


Copy-pasted new text from readme

jonmeow · 2020-07-28T18:22:16Z

docs/design/README.md

+- Block comments begin with `//\{`, and end with `//\}`. They are always at the
+  start of a line.


Rewritten with example

@zygoloid

The main comment on a review wasn't being handled, and this change interleaves it with the PR comments. GitHub treats these as different entities. I'm hiding reviews with no top-level comment; these didn't seem worth including empty comments. Links are being added to PR comments to make them easier to find. This means indenting the content, so now all comments (PR or review thread) are consistently indented, removing a parameter. Also, I'm adjusting the formatting of review threads to match. snippets for comparison: ``` #83 (comment) googlebot: All (the pull request submitter and all commit authors) CLAs are... #83 (review) chandlerc: Overall, I think this is a pretty significant improved direction... ``` and from a review thread: ``` https://github.com/carbon-language/carbon-lang/pull/83/files/9863da8#diff-8f28081abb21e65fba5a0b0b29404c78R16 - line 16; unresolved - diff: https://github.com/carbon-language/carbon-lang/pull/83/files/9863da8..HEAD#diff-8f28081abb21e65fba5a0b0b29404c78L16 josh11b: ```suggestion¶ - Block comments begin with a line starting with `/... jonmeow: "begin with a line starting with" phrasing is a little confusing t... josh11b: As I understand @zygoloid 's lexing proposal, there may be additio... jonmeow: Rewritten with example ```

- [RFC topic](https://forums.carbon-lang.dev/t/rfc-add-idiomatic-code-performance-and-developer-facing-docs-to-goals/105) - [Decision](https://forums.carbon-lang.dev/t/request-for-decision-add-idiomatic-code-performance-and-developer-facing-docs-to-goals/116) Co-authored-by: Chandler Carruth <chandlerc@gmail.com> Co-authored-by: Geoff Romer <gromer@google.com> Co-authored-by: Dmitri Gribenko <gribozavr@gmail.com> Most of this is addressing issue #106. Two new explicit sub-goals: - Idiomatic code should be performant, stemming from #106. - User-facing documentation, separate thought from #83 discussion. I think both of these are on people's minds and assumed, but still worth spelling out.

jonmeow and others added 15 commits May 20, 2020 08:36

Merge pull request #1 from carbon-language/master

2ae6b6f

Move firebase support into a src directory. (#15)

Merge remote-tracking branch 'upstream/master'

5bba3a8

Merge remote-tracking branch 'upstream/master'

98562a6

Merge pull request #2 from carbon-language/master

a05e9c3

Update fork

Merge pull request #3 from carbon-language/master

dfe42cb

Merge

Merge pull request #4 from carbon-language/master

3931951

Merge

Merge branch 'master' into lang-design-overview

fbbc0a8

Extensive updates based on review feedback.

f2d0fcf

Apply suggestions from code review

6be32d3

Co-authored-by: Jon Meow <46229924+jonmeow@users.noreply.github.com> Co-authored-by: josh11b <josh11b@users.noreply.github.com>

More tweaks

3c13624

Merge pull request #5 from carbon-language/master

43cfde9

Merge

Merge pull request #6 from carbon-language/master

b489c23

Merge

Merge pull request #7 from carbon-language/master

5b10b4d

Merge

Merge remote-tracking branch 'upstream/master'

6ce0f97

jonmeow added proposal A proposal WIP labels Jun 17, 2020

jonmeow added 4 commits June 17, 2020 12:34

Proposal adjustments

0132532

Merge branch 'master' into proposal-design-overview

5209564

toc

e72cf68

Evolving structure

2ec94a9

jonmeow marked this pull request as draft June 17, 2020 20:15

jonmeow added 4 commits June 17, 2020 13:15

Delete the old doc

2d69118

Trying different format

e220190

Progress

68b4e9b

Progress

4b0a788

jonmeow mentioned this pull request Jun 17, 2020

An incomplete, early, and in-progress overview of the language design. #22

Closed

josh11b reviewed Jun 17, 2020

View reviewed changes

docs/design/aliasing.md Outdated Show resolved Hide resolved

proposals/p0083.md Outdated Show resolved Hide resolved

Progress

4f83e44

jonmeow commented Jul 10, 2020

View reviewed changes

brycelelbach reviewed Jul 15, 2020

View reviewed changes

sidney13 added needs decision and removed proposal rfc Proposal with request-for-comment sent out labels Jul 16, 2020

geoffromer mentioned this pull request Jul 16, 2020

Requested changes to Carbon overview #114

Closed

josh11b reviewed Jul 16, 2020

View reviewed changes

Link PR 89

4809730

jonmeow mentioned this pull request Jul 23, 2020

Add idiomatic code performance and developer-facing docs to goals #120

Merged

josh11b mentioned this pull request Jul 25, 2020

Carbon: Lexical conventions #17

Closed

josh11b reviewed Jul 25, 2020

View reviewed changes

jonmeow added 2 commits July 27, 2020 16:00

Merge branch 'trunk' into proposal-design-overview

504c971

Update formatting

ddfc5f7

Addressing comments

7610342

jonmeow commented Jul 28, 2020

View reviewed changes

carbon marker

6c25f8a

sidney13 added proposal accepted Decision made, proposal accepted and removed needs decision labels Jul 30, 2020

sidney13 self-requested a review July 30, 2020 02:53

sidney13 approved these changes Jul 30, 2020

View reviewed changes

jonmeow added 2 commits July 30, 2020 11:25

Merge branch 'trunk' into proposal-design-overview

1d9a660

Rename interop per #114

d4550e3

jonmeow merged commit cec8a85 into carbon-language:trunk Jul 30, 2020

jonmeow deleted the proposal-design-overview branch July 30, 2020 18:37

jonmeow mentioned this pull request Jul 30, 2020

[proposal] An initial, draft, rough language design overview #18

Closed

jonmeow mentioned this pull request Feb 4, 2021

Proposal + decision can't be viewed at once #254

Closed

geoffromer mentioned this pull request Jul 14, 2022

Provisionally add let/var...else to the design overview #1388

Closed

		- `UpperCamelCase` for names of compile-time resolved constants, such that they
		can participate in the type system and type checking of the program.

		- Block comments begin with `//\{`, and end with `//\}`. The begin and end
		markers must be the only things on their lines.

	- Block comments begin with `//\{`, and end with `//\}`. The begin and end
	markers must be the only things on their lines.
	- Block comments begin with a line starting with `//\{`, and end with a line starting with `//\}`.

		- Block comments begin with `//\{`, and end with `//\}`. They are always at the
		start of a line.

An incomplete, early, and in-progress overview of the language design. #83

An incomplete, early, and in-progress overview of the language design. #83

Conversation

jonmeow commented Jun 17, 2020 • edited by sidney13 Loading

googlebot commented Jun 17, 2020

jonmeow left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jonmeow Jul 20, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jonmeow commented Jul 27, 2020 • edited Loading

jonmeow left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jonmeow commented Jun 17, 2020 •

edited by sidney13

Loading

jonmeow Jul 20, 2020 •

edited

Loading

jonmeow commented Jul 27, 2020 •

edited

Loading