From 317b41196bb28f1f1fe18650086adc91bc44d11f Mon Sep 17 00:00:00 2001 From: Josh L Date: Tue, 26 Aug 2025 23:10:03 +0000 Subject: [PATCH 1/5] Filling out template with PR 5990 --- proposals/p5990.md | 70 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) create mode 100644 proposals/p5990.md diff --git a/proposals/p5990.md b/proposals/p5990.md new file mode 100644 index 0000000000000..f64350a657a55 --- /dev/null +++ b/proposals/p5990.md @@ -0,0 +1,70 @@ +# Principle: the signature is the contract + + + +[Pull request](https://github.com/carbon-language/carbon-lang/pull/5990) + + + +## Table of contents + +- [Abstract](#abstract) +- [Problem](#problem) +- [Background](#background) +- [Proposal](#proposal) +- [Details](#details) +- [Rationale](#rationale) +- [Alternatives considered](#alternatives-considered) + + + +## Abstract + +TODO: Describe, in a succinct paragraph, the gist of this document. This +paragraph should be reproduced verbatim in the PR summary. + +## Problem + +TODO: What problem are you trying to solve? How important is that problem? Who +is impacted by it? + +## Background + +TODO: Is there any background that readers should consider to fully understand +this problem and your approach to solving it? + +## Proposal + +TODO: Briefly and at a high level, how do you propose to solve the problem? Why +will that in fact solve it? + +## Details + +TODO: Fully explain the details of the proposed solution. + +## Rationale + +TODO: How does this proposal effectively advance Carbon's goals? Rather than +re-stating the full motivation, this should connect that motivation back to +Carbon's stated goals and principles. This may evolve during review. Use links +to appropriate sections of [`/docs/project/goals.md`](/docs/project/goals.md), +and/or to documents in [`/docs/project/principles`](/docs/project/principles). +For example: + +- [Community and culture](/docs/project/goals.md#community-and-culture) +- [Language tools and ecosystem](/docs/project/goals.md#language-tools-and-ecosystem) +- [Performance-critical software](/docs/project/goals.md#performance-critical-software) +- [Software and language evolution](/docs/project/goals.md#software-and-language-evolution) +- [Code that is easy to read, understand, and write](/docs/project/goals.md#code-that-is-easy-to-read-understand-and-write) +- [Practical safety and testing mechanisms](/docs/project/goals.md#practical-safety-and-testing-mechanisms) +- [Fast and scalable development](/docs/project/goals.md#fast-and-scalable-development) +- [Modern OS platforms, hardware architectures, and environments](/docs/project/goals.md#modern-os-platforms-hardware-architectures-and-environments) +- [Interoperability with and migration from existing C++ code](/docs/project/goals.md#interoperability-with-and-migration-from-existing-c-code) + +## Alternatives considered + +TODO: What alternative solutions have you considered? From 7f7f657569dfe15ea0282fdb1aa51c05cce7d88c Mon Sep 17 00:00:00 2001 From: Josh L Date: Thu, 28 Aug 2025 19:11:17 +0000 Subject: [PATCH 2/5] Checkpoint progress. --- docs/project/principles/README.md | 4 + .../principles/signature_is_contract.md | 123 ++++++++++++++++++ proposals/p5990.md | 58 ++++----- 3 files changed, 152 insertions(+), 33 deletions(-) create mode 100644 docs/project/principles/signature_is_contract.md diff --git a/docs/project/principles/README.md b/docs/project/principles/README.md index 173afd5f88859..a860b4649cd52 100644 --- a/docs/project/principles/README.md +++ b/docs/project/principles/README.md @@ -21,9 +21,13 @@ principle can help achieve consistency across those multiple designs. Note that these principles seek to establish both the approaches the project wants to pursue, as well as those we want to exclude. +- [All APIs are library APIs](library_apis_only.md) - [Errors are values](error_handling.md) - [Information accumulation](information_accumulation.md) - [Low context-sensitivity](low_context_sensitivity.md) +- [Namespace cleanliness](namespace_cleanliness.md) - [Prefer providing only one way to do a given thing](one_way.md) +- [Progressive disclosure](progressive_disclosure.md) - [One static open extension mechanism](static_open_extension.md) - [Success criteria](success_criteria.md) +- [The signature is the contract](signature_is_contract.md) diff --git a/docs/project/principles/signature_is_contract.md b/docs/project/principles/signature_is_contract.md new file mode 100644 index 0000000000000..a43161861f766 --- /dev/null +++ b/docs/project/principles/signature_is_contract.md @@ -0,0 +1,123 @@ +# Principle: The signature is the contract + + + + + +## Table of contents + +- [Principle](#principle) +- [Applications of this principle](#applications-of-this-principle) +- [Background](#background) +- [Benefits and rationale](#benefits-and-rationale) +- [Exceptions](#exceptions) + + + +## Principle + +The declaration of an entity is authoritative for all typechecking information +about the aspects of the entity described by the entity's declaration (not +including things like the members of the entity). An entity's declaration should +generally be sufficient to typecheck uses of the entity, for uses that do not +reference any members of that entity. Information provided in a declaration is +not overridden or changed by its definition. + +## Applications of this principle + +- Parameters and return types are fully specified in a function declaration, + so Carbon can generally typecheck calls to a function given only its + declaration. This allows the definition of the function to be separately + compiled in the `impl` file, assuming its body is not needed for code + generation. + - This extends to class definitions only requiring declarations of their + member functions. +- Constraints can be implied only within a single declaration, see + [the alternative considered in proposal #818](/proposals/p0818.md#implied-constraints-across-declarations). +- The types and constraints on generic parameters to a type declaration (like + a `class` or `interface`) are specified in the declaration, not inferred + from the uses in they body of the definition. +- The type of a local variable is fixed by its declaration, not inferred from + later uses. This follows + [the (proposed) "unidirectional type propagation" principle](https://github.com/carbon-language/carbon-lang/pull/103). + +## Background + +- This is aligned with the + ["Low context-sensitivity" principle](low_context_sensitivity.md): a + function signature should be understandable without having to locate, read, + and understand its definition. +- This is in support of the + ["Information accumulation" principle](information_accumulation.md), which + motivates having separate forward declarations in addition to definitions. +- [Rust's Golden Rule](https://steveklabnik.com/writing/rusts-golden-rule/): + states a similar rule for Rust. + +## Benefits and rationale + +The more you can do with the declaration of an entity without its definition, +the more opportunities there are to move the definition to a file that is +compiled separately, improving build parallelism. + +This principle supports +[evolution of software written in Carbon](/docs/project/goals.md#software-and-language-evolution) +by separating the contract of an API from its implementation. This reduces the +amount of code that must be considered to understand the contract, and separates +changes that affect the contract from other changes. In this way, we can evolve +implementations without accidentally breaking its callers. + +This principle supports encapsulation, allowing isolation of implementation +details separate from API. + +This principle encourages the declaration of APIs to make their contract +explicit, contributing to self documentation. Favoring explicit contracts over +inferred requirements avoids creating problems that the compiler has to solve. +Particularly concerning is if requirements would have to be propagated multiple +steps, iterating until a fixed point is found. This can lead to longer compile +times and a more complex compiler implementation, hurting both the compiler +development and developer understanding of what the compiler does. + +The ability to use an entity with only its declaration allows breaking of +dependency cycles, by using forward declarations with fewer dependencies than +the full definition. This is instead of forward references, which are counter to +the ["information accumulation" principle](information_accumulation.md). + +Allowing a definition to override aspects of the corresponding declaration would +open the door to inconsistency. An example of how this is a problem in C++ + +```cpp +class Base {}; + +class Derived; + +// FIXME: commit to Derived not extending Base + +class Derived : public Base {}; + +// Inconsistency! +``` + +## Exceptions + +The main exception to this principle is when there is an explicit opt-in as part +of the signature or declaration to look in the body of the definition for +specific information that would normally be in the signature. Examples: + +- The `auto` keyword may be used to indicate that the return type of a + function is determined by the `return` statements in the body of the + function. +- The `template` keyword may be used to indicate that the constraints on a + generic parameter are not complete, and instead it will be determined by the + uses of that parameter in the body of the function. + +Both cases require the definition to be visible to the caller in order to type +check. + +There is also the exception that there can be non-member information about an +entity in the body of an entity's definition that may be needed to type check +uses. For example, an interface or named constraint may have requirements that +affect type checking of uses. diff --git a/proposals/p5990.md b/proposals/p5990.md index f64350a657a55..34371da6122f0 100644 --- a/proposals/p5990.md +++ b/proposals/p5990.md @@ -14,9 +14,7 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception - [Abstract](#abstract) - [Problem](#problem) -- [Background](#background) - [Proposal](#proposal) -- [Details](#details) - [Rationale](#rationale) - [Alternatives considered](#alternatives-considered) @@ -24,47 +22,41 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception ## Abstract -TODO: Describe, in a succinct paragraph, the gist of this document. This -paragraph should be reproduced verbatim in the PR summary. +Document principle "the signature is the contract" where Carbon requires the +information needed to use an entity is present in the entity's declaration. The +signature is authoritative, and is not modified by the definition body. ## Problem -TODO: What problem are you trying to solve? How important is that problem? Who -is impacted by it? - -## Background - -TODO: Is there any background that readers should consider to fully understand -this problem and your approach to solving it? +We have been using this principle informally to justify decisions, we should +formally adopt it. ## Proposal -TODO: Briefly and at a high level, how do you propose to solve the problem? Why -will that in fact solve it? +This principle is document in +[/docs/project/principles/signature_is_contract.md](/docs/project/principles/signature_is_contract.md), +added in this PR. -## Details +## Rationale -TODO: Fully explain the details of the proposed solution. +This principle is in support of these [Carbon goals](/docs/project/goals.md): -## Rationale +- [Language tools and ecosystem](/docs/project/goals.md#language-tools-and-ecosystem): + avoiding solving hard problems in the compiler. +- [Software and language evolution](/docs/project/goals.md#software-and-language-evolution): + making it easier to evolve Carbon code without breaking callers. +- [Code that is easy to read, understand, and write](/docs/project/goals.md#code-that-is-easy-to-read-understand-and-write): + by separating API contracts and making them explicit. + +It also supports these [Carbon principles](/docs/project/principles), as +described in +[the principle document](/docs/project/principles/signature_is_contract.md): -TODO: How does this proposal effectively advance Carbon's goals? Rather than -re-stating the full motivation, this should connect that motivation back to -Carbon's stated goals and principles. This may evolve during review. Use links -to appropriate sections of [`/docs/project/goals.md`](/docs/project/goals.md), -and/or to documents in [`/docs/project/principles`](/docs/project/principles). -For example: - -- [Community and culture](/docs/project/goals.md#community-and-culture) -- [Language tools and ecosystem](/docs/project/goals.md#language-tools-and-ecosystem) -- [Performance-critical software](/docs/project/goals.md#performance-critical-software) -- [Software and language evolution](/docs/project/goals.md#software-and-language-evolution) -- [Code that is easy to read, understand, and write](/docs/project/goals.md#code-that-is-easy-to-read-understand-and-write) -- [Practical safety and testing mechanisms](/docs/project/goals.md#practical-safety-and-testing-mechanisms) -- [Fast and scalable development](/docs/project/goals.md#fast-and-scalable-development) -- [Modern OS platforms, hardware architectures, and environments](/docs/project/goals.md#modern-os-platforms-hardware-architectures-and-environments) -- [Interoperability with and migration from existing C++ code](/docs/project/goals.md#interoperability-with-and-migration-from-existing-c-code) +- [Information accumulation](/docs/project/principles/information_accumulation.md) +- [Low context-sensitivity](/docs/project/principles/low_context_sensitivity.md) ## Alternatives considered -TODO: What alternative solutions have you considered? +The main alternative is for contracts to be inferred from definitions. This +means this contract is not explicit in the source code, which we believe is an +approach that does not scale to large teams working together on the same code. From dad0587a1e5e1fdaa4f18d32a81d68b2b8424d1c Mon Sep 17 00:00:00 2001 From: Josh L Date: Thu, 28 Aug 2025 22:13:26 +0000 Subject: [PATCH 3/5] C++ inconsistency --- .../principles/signature_is_contract.md | 22 ++++++++----------- 1 file changed, 9 insertions(+), 13 deletions(-) diff --git a/docs/project/principles/signature_is_contract.md b/docs/project/principles/signature_is_contract.md index a43161861f766..06339ae96858a 100644 --- a/docs/project/principles/signature_is_contract.md +++ b/docs/project/principles/signature_is_contract.md @@ -87,19 +87,15 @@ the full definition. This is instead of forward references, which are counter to the ["information accumulation" principle](information_accumulation.md). Allowing a definition to override aspects of the corresponding declaration would -open the door to inconsistency. An example of how this is a problem in C++ - -```cpp -class Base {}; - -class Derived; - -// FIXME: commit to Derived not extending Base - -class Derived : public Base {}; - -// Inconsistency! -``` +open the door to inconsistency. This is something that can happen in C++ +(potentially leading to ODR violations): + +- The behaviour of `&x` where `x` is an lvalue of an incomplete class type, + where you can't do the lookup for a member named `operator&`, see + [this note on C++ unary operators](https://eel.is/c++draft/expr#unary.op-5). +- The MSVC ABI has different member pointer representations for different + kinds of classes, but you can use a pointer to member before the class is + defined. ## Exceptions From 7f2d8f85f6caa81a67227adf1ca2d0f9802993d9 Mon Sep 17 00:00:00 2001 From: Josh L Date: Thu, 28 Aug 2025 22:15:29 +0000 Subject: [PATCH 4/5] Checkpoint progress. --- proposals/p5990.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/proposals/p5990.md b/proposals/p5990.md index 34371da6122f0..115ec933c2507 100644 --- a/proposals/p5990.md +++ b/proposals/p5990.md @@ -1,4 +1,4 @@ -# Principle: the signature is the contract +# Principle: The signature is the contract