Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
wants to merge 5 commits into from
Closed

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

wants to merge 5 commits into from

Conversation

chandlerc
Copy link
Contributor

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 ready for full review yet. Some specific changes
that I'm planning to make:

  • I want to reorganize the sections of the document a bit. The current
    structure is somewhat outdated and I have better ideas about how to
    organize these things.
  • Some of the sections are quite old and don't come close to current
    thinking. While to an extent this is inevitable, I'd like to clean at
    least a few of them up.

However, as is 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.

Fixes #18.

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.
@chandlerc
Copy link
Contributor Author

I think this is in a state where folks can start reading it and discussing. A couple of points on discussion here though...

The big one: on any specific topic, please try to keep discussion fairly light and high-level. I'll try to add some rough notes about major high-level concerns, but it is easy to become swamped in those. This is not intended to propose any particular set of details as the path forward, only to collect a high level picture (even if stale & inaccurate from time to time). The right place to dig into details, or really push on any specific direction is through a detailed proposal in that area.

I am especially interested if there are major improvements people would like to see in the overall organization. So far, I've not loved any of the organization, but this one seems at least "OK" for now. But if there are concrete suggestions for ways to structure that would be better, I'd love to hear ideas and discuss them.

Also interested in better ways to phrase and word the top-level introduction to best convey the nature and purpose of the document -- serving as an overview and index across the design space, not pushing any one area forward with "this is how it should be".

Copy link
Contributor

@josh11b josh11b left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't want to get into an extended debate here, but I thought making an attempt to make the document a bit more accurate would be beneficial. I think it would be reasonable to just delete sections that we know are inaccurate until later if you want to get this in quickly.

> **Note**: this implies that other names within your own package but not
> declared within the file must be found via the package name. It isn't clear if
> this is the desirable end state. We need to consider alternatives where names
> from the same module or any module in the same package are made immediately
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When you say "module" here do you mean the "library" you defined above?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, good catch.

Comment on lines 200 to 201
Carbon also disallows the use of shadowed unqualified names, but not the
_declaration_ of shadowing names in different named scopes. Because all
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I did not follow this -- perhaps an example would make it clearer?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

Comment on lines 205 to 206
that adding names to the standard library or importing a new package (both of
which bring new names into the current package's scope) doesn't force renaming
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This bit about adding names to a package that is imported adds names to the package's scope doesn't sound consistent with what you said before, nor consistent with how I expect/want things to work.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tried to make this more clear in the example, but let me know if it still isn't clear.

That said, I'm not really trying to endorse this. I'm happy removing a bunch of this if you want -- I mostly think it is interesting to consider the underlying ideas of restricting shadowing by limiting unqualified name lookup and falling back to qualified name lookup.

Comment on lines 238 to 239
- Bitwise: `2 & 3`, `2 | 4`, `3 ^ 1`, `1 <&lt; 3`, `8 >> 1`, `~7`
- Relational: `2 == 2`, `3 != 4`, `5 &lt; 6`, `7 > 6`, `8 &lt;= 8`, `8 >= 8`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Bitwise: `2 & 3`, `2 | 4`, `3 ^ 1`, `1 <&lt; 3`, `8 >> 1`, `~7`
- Relational: `2 == 2`, `3 != 4`, `5 &lt; 6`, `7 > 6`, `8 &lt;= 8`, `8 >= 8`
- Bitwise: `2 & 3`, `2 | 4`, `3 ^ 1`, `1 << 3`, `8 >> 1`, `~7`
- Relational: `2 == 2`, `3 != 4`, `5 < 6`, `7 > 6`, `8 <= 8`, `8 >= 8`

I've noticed this is an issue with our docs-to-markdown exporter.

docs/designs/language-design-overview.md Outdated Show resolved Hide resolved
Comment on lines 952 to 956
should cast or convert the argument to control the deduction. The explicit type
is passed after a runtime parameter. While this makes that type unavailable to
the declaration of the runtime parameter, it still is a true type and available
to use as a type even within the remaining parts of the template function
declaration.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suspect these last sentences are talking about something that is no longer relevant.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I just think I was using really bad words. Anyways, rewritten to be I think somewhat more clear.

Comment on lines 958 to 967
> **Note**: there is an important open question about how to distinguish between
> a non-type parameter of a template function which is a normal runtime
> parameter and one which must trigger instantiation and become available in the
> function as a compile time constant. Currently, the most appealing technique
> is an annotation of the parameter itself, but we still don't have a very
> appealing suggestion for how to spell this annotation without making the
> declaration excessively verbose. An alternative would be to give up on the
> single-parameter sequence and require the template parameters to be separate
> so the above becomes `template fn Convert[Type: T](Type: U)(T: source) -> U`
> and the call becomes `Convert(Float)(i)`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also out of date.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Deleted.

Comment on lines +828 to +829
> **TODO:** Update all of this to match the generics proposal when we have a
> draft published, and link to it.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would be much more comfortable omitting these sections until they can be rewritten than including them as-is.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We discussed this offline a bit... I agree that the sections don't currently make much sense, just representing very dated and not coherent idle speculation... However, I also feel like there is some minimal value here to help people begin thinking outside of the C++ constrnucts of templates and inheritance, and to provide some common syntax primitives around interfaces that can be useful in examples and other discussions.

I'm currently rewritting the entire section to both be much more minimal while still giving some flavor of the directions we're exploring here. I'll update again when I have new text here for a fresh look and then let's see if we can arrive at something that still provides this "flavor" level value without ending up misleading.

Comment on lines 59 to 74
be the only non-whitespace on the line. Carbon also supports a nestable block
comment syntax:

```
/*
...
/*
...
*/
...
*/
```

While these use the block comment syntax of C and C++, they allow nesting much
like with Swift. The opening (`/*`) and closing (`*/`) are required to be the
first and last (respectively) thing on the line. Both of these comment styles
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd just delete this bit about /* ... */ for now. Including it and then having notes about them maybe not actually being included is too much detail for an overview document like this, which has a lot to cover, and any place we can shorten will be beneficial.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure, tried to shorten up a bit.

a local variable named `p` which is then returned.

### Pattern matching as function overload resolution

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add TODO

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

@jonmeow jonmeow added proposal A proposal WIP labels Jun 3, 2020
chandlerc and others added 4 commits June 9, 2020 23:52
Co-authored-by: Jon Meow <46229924+jonmeow@users.noreply.github.com>
Co-authored-by: josh11b <josh11b@users.noreply.github.com>
Copy link
Contributor Author

@chandlerc chandlerc left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

First off, thanks for the thorough review. =D

I think I got through all of the comments left and responded. I'll make a second pass to double check and mark all the ones that seem definitive as "resolved" tomorrow.

Appreciate not going too far down the debate path here. I think there are really two areas with substantial issues:

  1. Tuples (especially w.r.t. function calls)
  2. Generics (and templates, etc)

For 2, I've got a pretty clear idea of what might both be a more useful and much more up-to-date and accurate summary for generics. I've deleted most of the egregious text and left some TODOs, I plan to fill that in before landing though, I just didn't want to wait on finishing that text to send out the rest of my updates. The template sections I was able to pretty quickly update to something plausible (or at least, they may be plausible once I address my TODOs to give the introduction section that ties them together).

For 1, I've responded inline and tried to re-focus the text in the document on the more useful (and I think less interesting / difficult / uncertain (to me) aspects. It still isn't perfect, and I've tried to make sure there are at least very explicit notes about the uncertainty here. Unsure if this is really enough in the way of disclaimer to avoid confusion, but at least for me it seems pretty close. Happy to iterate here until we find something that strikes a reasonable balance though.

docs/designs/language-design-overview.md Show resolved Hide resolved
docs/designs/language-design-overview.md Show resolved Hide resolved
Comment on lines 59 to 74
be the only non-whitespace on the line. Carbon also supports a nestable block
comment syntax:

```
/*
...
/*
...
*/
...
*/
```

While these use the block comment syntax of C and C++, they allow nesting much
like with Swift. The opening (`/*`) and closing (`*/`) are required to be the
first and last (respectively) thing on the line. Both of these comment styles
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure, tried to shorten up a bit.

We'll get into more detail about what these mean and how they all work as we go
along.

### Basic names and scopes
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good call, added a section and restructured a bit so it fits.

> **Note**: this implies that other names within your own package but not
> declared within the file must be found via the package name. It isn't clear if
> this is the desirable end state. We need to consider alternatives where names
> from the same module or any module in the same package are made immediately
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, good catch.

and run-time parameters.

```
template fn Convert[Type: T](T: source, Type: U) -> U {
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done and entire section rewritten. Similar to above, this references as-yet-unwritten high level ideas that are common such as implicit parameters. Will add that as I get the generics bit fleshed out and then need to make sure this lines up coherently. But it is at least much less actively wrong/misleading.

Comment on lines 952 to 956
should cast or convert the argument to control the deduction. The explicit type
is passed after a runtime parameter. While this makes that type unavailable to
the declaration of the runtime parameter, it still is a true type and available
to use as a type even within the remaining parts of the template function
declaration.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I just think I was using really bad words. Anyways, rewritten to be I think somewhat more clear.

Comment on lines 958 to 967
> **Note**: there is an important open question about how to distinguish between
> a non-type parameter of a template function which is a normal runtime
> parameter and one which must trigger instantiation and become available in the
> function as a compile time constant. Currently, the most appealing technique
> is an annotation of the parameter itself, but we still don't have a very
> appealing suggestion for how to spell this annotation without making the
> declaration excessively verbose. An alternative would be to give up on the
> single-parameter sequence and require the template parameters to be separate
> so the above becomes `template fn Convert[Type: T](Type: U)(T: source) -> U`
> and the call becomes `Convert(Float)(i)`.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Deleted.

#### Specialization

An important feature of templates in C++ is the ability to customize how they
end up specialized for specific types. Carbon also supports this for templates:
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yes, lemme just say that too....

#### Specialization

An important feature of templates in C++ is the ability to customize how they
end up specialized for specific types. Carbon also supports this for templates:
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also tried to clarify that by leveraging pattern matching there is potentially more going on here. The only hting I want to really be concrete about though is that this gives us a potential integrated way to get extremely comparable facilities to what C++ provides so we know we're covering that space.

import Shadow library OtherLib;

// We can reference the imported library:
alias ??? OtherLibType = Shadow.SomeType;
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
alias ??? OtherLibType = Shadow.SomeType;
alias ??? OtherLibType = OtherLib.Shadow.SomeType;

I'm a bit confused here, isn't "Shadow" here unqualified, and thus an error? Shouldn't this require OtherLib.Shadow.SomeType?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this whole example (and possibly idea?) is just broken, and so I'm deleting all of it. We shouldn't figure out how this does work here, that should be in the naming proposal. I'll think more about what we really want around shadowing and try again in that doc! =D

with parentheses to have clear and distinct syntax and match both the common
case (multiple parameters) and common convention in programming languages around
function notation. `Int*` `Int*?` `Int[]`
Generally, functions pattern match a single tuple value of the arguments (with
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Broad comment -- I was digging and the dev style guide strongly discourages use of parentheticals, you might want to go through removing uses.
https://developers.google.com/style/parentheses

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a good point, I'm going through and trying to clean up my use of them. It's a long standing habit, so apologies when I inevitable regress, but definitely keep calling it out.

I think there are some uses that (as the guide says) are OK when judiciously used... but long parentheticals like this seem clearly better written differently. =]

Copy link
Contributor Author

@chandlerc chandlerc left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Replying to the new comments from Jon as I work on these and some other updates.

import Shadow library OtherLib;

// We can reference the imported library:
alias ??? OtherLibType = Shadow.SomeType;
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this whole example (and possibly idea?) is just broken, and so I'm deleting all of it. We shouldn't figure out how this does work here, that should be in the naming proposal. I'll think more about what we really want around shadowing and try again in that doc! =D

with parentheses to have clear and distinct syntax and match both the common
case (multiple parameters) and common convention in programming languages around
function notation. `Int*` `Int*?` `Int[]`
Generally, functions pattern match a single tuple value of the arguments (with
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a good point, I'm going through and trying to clean up my use of them. It's a long standing habit, so apologies when I inevitable regress, but definitely keep calling it out.

I think there are some uses that (as the guide says) are OK when judiciously used... but long parentheticals like this seem clearly better written differently. =]


Our current proposed naming convention, which we at least are attempting to
follow within Carbon documentation in order to keep code samples as consistent
as possible:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
as possible:
as possible, is:


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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it worth mentioning here that we intend to use lower_snake_case for keywords too?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, and highlight (ba-dum) that syntax highlighting helps those stand out on their own, and why. I'll make a suggestion on Jon's new structure.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually, this seems better handled in the lexical conventions. This section is about the naming conventions within identifiers, and I feel like bringing up keywords is likely to just be confusing.

docs/designs/language-design-overview.md Show resolved Hide resolved
Comment on lines +235 to +239
> **Note**: this implies that other names within your own package but not
> declared within the file must be found via the package name. It isn't clear if
> this is the desirable end state. We need to consider alternatives where names
> from the same library or any library in the same package are made immediately
> visible within the package scope for unqualified name lookup.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When deciding what to do here, we should think about whether we want to support compilation at a finer granularity than package-at-a-time. We have evidence that the Rust crate-at-a-time compilation model results in compilation performance problems.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed. Not sure there is anything we can say this early though?

Comment on lines +244 to +252
Because all unqualified name lookup is locally controlled, shadowing isn't
needed for robustness and is a long and painful source of bugs over time.
Disallowing it provides simple, predictable rules for name lookup. However, it
is important that adding names to the standard library or importing a new
package (both of which bring new names into the current package's scope) doesn't
force renaming interfaces that may have many users. To accomplish this, we allow
code to declare shadowing names, but references to that name must be qualified.
For package-scope names, this can be done with an explicit use of the current
package name: `PackageName.ShadowingName`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is adding a new name to the prelude a breaking change? (Would you need to update all existing code to stop using that name as an unqualified identifier first, before upgrading?) Perhaps we could give names from the prelude the same treatment that #17 suggests for keywords: if you declare them anywhere in a file, you don't get to use them with their built-in meaning in that file.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm OK with adding a new name being a breaking change exactly as much as I'm OK with adding keywords being a breaking change. =] And I'm also happy finding similar mechanisms to allow people to handle the fallout in sustainable ways, as long as neither one stops progress of adding keywords when justified. =D Anyways, probably best to handle it in #17 rather than here.

```
std::int64_t Sum(std::int64_t a, std::int64_t b);

// Or with the new trailing return type syntax:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
// Or with the new trailing return type syntax:
// Or with trailing return type syntax:

(It's not all that new any more.)

package MyProgram library Entry;

fn Run() -> Bool {
Print("Hello World!");
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This isn't the right place for this comment, but: I view Carbon as being a language for writing code at scale, where you probably don't want to use Print and would instead want some domain-specific output mechanism; therefore, I don't think it should be visible by default in Carbon source files -- I think people should be required to think at least a little bit before using it. That said, I think

  • We should be able to support the kinds of small utilities where Print is useful. Putting a bunch of such functionality into some standard library "tool utilities" package seems like a good idea.

  • Being able to print out a debugging string is certainly useful, and it might be reasonable to make functionality for that be available by default.

> **TODO:** Need a comprehensive design document to underpin these, and then
> link to it here.

These types are fundamental to the language as they aren't comprised of other
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
These types are fundamental to the language as they aren't comprised of other
These types are fundamental to the language as they aren't formed from other

(https://grammarist.com/usage/compose-comprise/)

Comment on lines +629 to +631
> should be defined in Carbon code rather than special. Clearly they can't be
> directly implemented w/o help, but it might still be useful to force the
> programmer-observed interface to reside in code. However, this can cause
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not certain that we can't implement many of these types directly without help. For example, I could imagine allowing a direct implementation of Type for a given value, that allows Carbon code to specify layout properties of a type. There are circularity problems to deal with (eg, what is the return type of Type.Size?) but perhaps we could cut that cycle somewhere that's invisible to Carbon programs.

that is not available as part of the type system would be named `n`, even if it
happened to be immutable or only take on a single value. Functions and most
types will be in `UpperCamelCase`, but a type where only run-time type
information queries are available would end up as `lower_snake_case`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How does this apply to generic arguments to a function, which are compile-time constants at the call site but not within the function body? This explanation makes it sound like they should be lowercase, since you can't use them in compile-time-only contexts, but most of the examples I've seen use uppercase.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't really follow, I think the generic examples are using the types as compile-time constants...

fn GenericF[SomeInterface:$ GenericT](GenericT: value) -> Void

Here, GenericT is used in a compile time context -- it is part of the parameter declaration?

> explicit types or other questions in this space). That was a very limited PhD
> student's study of Java programmers that seemed to indicate improved latency
> for recalling the type of a given variable name with types on the left (as in
> C++). However, those results are _far_ from conclusive.
Copy link
Contributor

@mconst mconst Jun 17, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you're looking for data points on how people respond to this syntax: this tripped me up in your presentation when I tried to read example Carbon code for the first time, and it continues to trip me up over a month later. Literally every other language I know of that uses this syntax does it in the other order.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yep, this is a point that I think folks are very much thinking about. Happy to talk more in depth about this at some point if you want, but probably this doc isn't the best place.

@chandlerc
Copy link
Contributor Author

@jonmeow has what I think is a really nice (but different) structured approach in #83 that I much prefer, and so I'm closing this PR out in favor of his for now.

I've tried to respond to some of the questions here. I think most of the immediate adjustments suggested have been reflected in #83, but if anyone sees one that got missed, I'll try to keep following this thread just-in-case.

@chandlerc chandlerc closed this Jun 19, 2020
jonmeow added a commit that referenced this pull request Jul 30, 2020
#83)

Co-authored by: chandlerc

- Based on [PR 22](#83)
- [Idea topic](https://forums.carbon-lang.dev/t/proposal-for-an-incomplete-rough-high-level-overview-ready-for-early-feedback/52)
- [RFC](https://forums.carbon-lang.dev/t/rfc-an-incomplete-early-and-in-progress-overview-of-the-language-design/73)
- [Decision announcement](https://forums.carbon-lang.dev/t/accepted-an-incomplete-early-and-in-progress-overview-of-the-language-design/110)

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 #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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
proposal A proposal
Projects
None yet
Development

Successfully merging this pull request may close these issues.

[proposal] An initial, draft, rough language design overview
5 participants