carbon-lang/docs/design/code_and_name_organization

Code and name organization

Table of contents

• Goals and philosophy
• Overview
  • Sizing packages and libraries
  • Imports
• Details
  • Source file introduction
  • Name paths
    • package syntax
  • Packages
    • Shorthand notation for libraries in packages
    • Package name conflicts
  • Libraries
    • Exporting entities from an API file
    • Granularity of libraries
    • Exporting namespces
  • Imports
    • Imports from the current package
  • Namespaces
    • Re-declaring imported namespaces
    • Aliasing
• Caveats
  • Package and library name conflicts
  • Potential refactorings
    • Update imports
    • Between api and impl files
    • Other refactorings
  • Preference for few child namespaces
  • Redundant markers
• Open questions
  • Different file extensions
  • Imports from other languages
  • Imports from URLs
  • Test file type
• Alternatives
  • Packages
    • Name paths for package names
    • Referring to the package as package
    • Remove the library keyword from package and import
    • Rename package concept
    • No association between the file system path and library/namespace
  • Libraries
    • Allow exporting namespaces
    • Allow importing implementation files from within the same library
    • Alternative library separators and shorthand
      • Single-word libraries
    • Collapse API and implementation file concepts
      • Automatically generating the API separation
    • Collapse file and library concepts
    • Collapse the library concept into packages
    • Collapse the package concept into libraries
    • Different file type labels
    • Function-like syntax
    • Inlining from implementation files
    • Library-private access controls
    • Managing API versus implementation in libraries
    • Multiple API files
    • Name paths as library names
  • Imports
    • Block imports
    • Block imports of libraries of a single package
    • Broader imports, either all names or arbitrary code
    • Direct name imports
    • Optional package names
  • Namespaces
    • File-level namespaces
    • Scoped namespaces

Goals and philosophy

Important Carbon goals for code and name organization are:

• Language tools and ecosystem

  • Tooling support is important for Carbon, including the possibility of a package manager.

  • Developer tooling, including both IDEs and refactoring tools, are expected to exist and be well-supported.

• Software and language evolution:

  • We should support libraries adding new structs, functions or other identifiers without those new identifiers being able to shadow or break existing users that already have identifiers with conflicting names.

  • We should make it easy to refactor code, including moving code between files. This includes refactoring both by humans and by developer tooling.

• Fast and scalable development:

  • It should be easy for developer tooling to parse code, without needing to parse imports for context.

  • Structure should be provided for large projects to opt into features which will help maintain scaling of their codebase, while not adding burdens to small projects that don't need it.

Overview

Carbon source files have a .carbon extension, such as geometry.carbon. These files are the basic unit of compilation.

Each file begins with a declaration of which package^[define] it belongs in. The package is the unit of distribution. The package name is a single identifier, such as Geometry. An example API file in the Geometry package would start with:

package Geometry api;

A tiny package may consist of a single library with a single file, and not use any further features of the package keyword.

It is often useful to use separate files for the API and its implementation. This may help organize code as a library grows, or to let the build system distinguish between the dependencies of the API itself and its underlying implementation. Implementation files allow for code to be extracted out from the API file, while only being callable from other files within the library, including both API and implementation files. Implementation files are marked by both naming the file to use an extension of .impl.carbon and instead start with:

package Geometry impl;

However, as a package adds more files, it will probably want to separate out into multiple libraries^[define]. A library is the basic unit of dependency. Separating code into multiple libraries can speed up the overall build while also making it clear which code is being reused. For example, an API file adding the library Shapes to the Geometry package, or Geometry//Shapes in shorthand, would start with:

package Geometry library "Shapes" api;

As code becomes more complex, and users pull in more code, it may also be helpful to add namespaces^[define] to give related entities consistently structured names. A namespace affects the name path^[define] used when calling code. For example, with no namespace, if a Geometry package defines Circle then the name path will be Geometry.Circle. However, it can be named Geometry.TwoDimensional.Circle with a namespace; for example:

package Geometry library "Shapes" api;
namespace TwoDimensional;
struct TwoDimensional.Circle { ... };

This scaling of packages into libraries and namespaces is how Carbon supports both small and large codebases.

Sizing packages and libraries

A different way to think of the sizing of packages and libraries is:

• A package is a GitHub repository.
  • Small and medium projects that fit in a single repository will typically have a single package. For example, a medium-sized project like Abseil could still use a single Abseil package.
  • Large projects will have multiple packages. For example, Mozilla may have multiple packages for Firefox and other efforts.
• A library is a few files that provide an interface and implementation, and should remain small.
  • Small projects will have a single library when it's easy to maintain all code in a few files.
  • Medium and large projects will have multiple libraries. For example, Boost Geometry's Distance interface and implementation might be its own library within Boost, with dependencies on other libraries in Boost and potentially other packages from Boost.
    • Library names could be named after the feature, such as library "Algorithms", or include part of the path to reduce the chance of name collisions, such as library "Geometry/Algorithms".

Packages may choose to expose libraries that expose unions of interfaces from other libraries within the package. However, doing so would also provide the transitive closure of build-time dependencies, and is likely to be discouraged in many cases.

Imports

The import keyword supports reusing code from other files and libraries.

For example, to use Geometry.Circle from the Geometry//Shapes library:

import Geometry library "Shapes";

fn Area(Geometry.Circle circle) { ... };

The library keyword is optional for import, and its use should parallel that of library on the package of the code being imported.

Details

Source file introduction

Every source file will consist of, in order:

1. One package statement.
2. A section of zero or more import statements.
3. Source file body, with other code.

Comments and blank lines may be intermingled with these sections. Metaprogramming code may also be intermingled, so long as the outputted code is consistent with the enforced ordering. Other types of code must be in the source file body.

Name paths

Name paths are defined above as sequences of identifiers separated by dots. This syntax may be loosely expressed as a regular expression:

IDENTIFIER(\.IDENTIFIER)*

Name conflicts are addressed by name lookup.

package syntax

Packages

The package keyword's syntax may be loosely expressed as a regular expression:

package IDENTIFIER (library STRING)? (api|impl);

For example:

package Geometry library "Objects/FourSides" api;

Breaking this apart:

• The identifier passed to the package keyword, Geometry, is the package name and will prefix both library and namespace paths.
  • The package keyword also declares a package entity matching the package name. A package entity is almost identical to a namespace entity, except with some package/import-specific handling. In other words, if the file declares struct Line, that may be used from within the file as both Line directly and Geometry.TwoDimensional.Line using the Geometry package entity created by the package keyword.
• When the optional library keyword is specified, sets the name of the library within the package. In this example, the Geometry//Objects/FourSides library will be used.
• The use of the api keyword indicates this is an API files as described under libraries. If it instead had impl, this would be an implementation file.

Because the package keyword must be specified exactly once in all files, there are a couple important and deliberate side-effects:

• Every file will be in precisely one library.
  • A library still exists even when there is no explicit library argument, such as package Geometry api;. This could be considered equivalent to package Geometry library "" api;, although we should not allow that specific syntax as error-prone.
• Every entity in Carbon will be in a namespace, even if its namespace path consists of only the package name. There is no "global" namespace.
  • Every entity in a file will be defined within the namespace described in the package statement.
  • Entities within a file may be defined in child namespaces.

Files contributing to the Geometry//Objects/FourSides library must all start with package Geometry library "Objects/FourSides", but will differ on api/impl types.

Shorthand notation for libraries in packages

Library names may also be referred to as PACKAGE//LIBRARY as shorthand in text. PACKAGE//default will refer to the name of the library used when no library argument is specified, although PACKAGE may also be used in situations where it is unambiguous that it still refers to the default library.

It's recommended that libraries use a single / for separators where desired, in order to distinguish between the // of the package and / separating library segments. For example, Geometry//Objects/FourSides uses a single / to separate the Object/FourSides library name.

Package name conflicts

Because the package also declares a namespace entity with the same name, conflicts with the package name are possible. We do not support packages providing entities with the same name as the package.

For example, this is a conflict for DateTime:

package DateTime api;

struct DateTime { ... };

This declaration is important for implementation files, which implicitly import the library's API, because it keeps the package name as an explicit entity in source files.

Note that imported name conflicts are handled differently.

Libraries

Every Carbon library consists of one or more files. Each Carbon library has a primary file that defines its API, and may optionally contain additional files that are implementation.

• An API file's package will have api. For example, package Geometry library "Shapes" api;
  • API filenames must have the .carbon extension. They must not have a .impl.carbon extension.
  • API file paths will correspond to the library name.
    • The precise form of this correspondence is undetermined, but should be expected to be similar to a "Math/Algebra" library being in a "Math/Algebra.carbon" file path.
    • The package will not be used when considering the file path.
• An implementation file's package will have impl. For example, package Geometry library "Shapes" impl;.
  • Implementation filenames must have the .impl.carbon extension.
  • Implementation file paths need not correspond to the library name.
  • Implementation files implicitly import the library's API. Implementation files cannot import each other. There is no facility for file or non-api imports.

The difference between API and implementation will act as a form of access control. API files must compile independently of implementation, only importing from APIs from other libraries. API files are also visible to all files and libraries for import. Implementation files only see API files for import, not other implementation files.

When any file imports a library's API, it should be expected that the transitive closure of imported files from the primary API file will be a compilation dependency. The size of that transitive closure affects compilation time, so libraries with complex implementations should endeavor to minimize their API imports.

Libraries also serve as a critical unit of compilation. Dependencies between libraries must be clearly marked, and the resulting dependency graph will allow for separate compilation.

Exporting entities from an API file

In order to actually be part of a library's API, entities must both be in the API file and explicitly marked as an API. This is done using the api keyword, which is only allowed in the API file. For example:

package Geometry library "Shapes" api;

// Circle is marked as an API, and will be available to other libraries as
// Geometry.Circle.
api struct Circle { ... }

// CircleHelper is not marked as an API, and so will not be available to other
// libraries.
fn CircleHelper(Circle circle) { ... }

// Only entities in namespaces should be marked as an API, not the namespace
// itself.
namespace Operations;

// Operations.GetCircumference is marked as an API, and will be available to
// other libraries as Geometry.Operations.GetCircumference.
api fn Operations.GetCircumference(Circle circle) { ... }

This means that an API file can contain all implementation code for a library. However, separate implementation files are still desirable for a few reasons:

• It will be easier for readers to quickly scan an API-only file for API documentation.
• Reducing the amount of code in an API file can speed up compilation, especially if fewer imports are needed. This can result in transitive compilation performance improvements for files using the library.
• From a code maintenance perspective, having smaller files can make a library more maintainable.

Use of the api keyword is not allowed within files marked as impl.

Granularity of libraries

The compilation graph of Carbon will generally consist of api files depending on each other, and impl files depending only on api files. Compiling a given file requires compiling the transitive closure of api files first. Parallelization of compilation is then limited by how large that transitive closure is, in terms of total volume of code rather than quantity. This also affects build cache invalidation.

In order to maximize opportunities to improve compilation performance, we will encourage granular libraries. Conceptually, we want libraries to be very small, possibly containing only a single class. The choice of only allowing a single api file per library should help encourage developers to write small libraries.

Exporting namespces

Any entity may be marked with api except for namespace and package entities. That is, api namespace Sha256; is invalid code. Instead, namespaces are implicitly exported based on the name paths of other entities marked as api.

For example, given this code:

package Checksums library "Sha" api;

namespaces Sha256;

api fn Sha256.HexDigest(Bytes data) -> String { ... }

Calling code may look like:

package Caller api;

import Checksums library "Sha";

fn Process(Bytes data) {
  ...
  var String digest = Checksums.Sha256.HexDigest(data);
  ...
}

In this example, the Sha256 namespace is exported as part of the API implicitly.

Imports

The import keyword supports reusing code from other files and libraries. The import keyword's syntax may be loosely expressed as a regular expression:

import IDENTIFIER (library NAME_PATH)?;

An import declares a package entity named after the imported package, and makes api-tagged entities from the imported library through it. The full name path is a concatenation of the names of the package entity, any namespace entities applied, and the final entity addressed. Child namespaces or entities may be aliased if desired.

For example, given a library:

package Math api;
namespace Trigonometry;
api fn Trigonometry.Sin(...);

Calling code would import it and use it like:

package Geometry api;

import Math;

fn DoSomething() {
  ...
  Math.Trigonometry.Sin(...);
  ...
}

Repeat imports from the same package reuse the same package entity. For example, this produces only one Math package entity:

import Math;
import Math library "Trigonometry";

Imports from the current package

Entities defined in the current file may be used without mentioning the package prefix. However, other symbols from the package must be imported and accessed through the package namespace just like symbols from any other package.

For example:

package Geometry api;

// This is required even though it's still in the Geometry package.
import Geometry library "Shapes";

// Circle must be referenced using the Geometry namespace of the import.
fn GetArea(Geometry.Circle c) { ... }

Namespaces

Namespaces offer named paths for entities. Namespaces may be nested. Multiple libraries may contribute to the same namespace. In practice, packages may have namespaces such as Testing containing entities that benefit from an isolated space but are present in many libraries.

The namespace keyword's syntax may loosely be expressed as a regular expression:

namespace NAME_PATH;

The namespace keyword declares a namespace entity. The namespace is applied to other entities by including it as a prefix when declaring a name. For example:

package Time;

namespace Timezones.Internal;
struct Timezones.Internal.RawData { ... }

fn ParseData(Timezones.Internal.RawData data);

A namespace declaration adds the first identifier in the name path as a name in the file's namespace. In the above example, after declaring namespace Timezones.Internal;, Timezones is available as an identifier and Internal is reached through Timezones.

Re-declaring imported namespaces

Namespaces may exist on imported package entities, in addition to being declared in the current file. However, even if the namespace already exists in an imported library from the current package, the namespace must still be declared locally in order to add symbols to it.

For example, if the Geometry//Shapes/ThreeSides library provides the Geometry.Shapes namespace, this code is still valid:

package Geometry library "Shapes/FourSides" api;

import Geometry library "Shapes/ThreeSides";

// This does not conflict with the existence of `Geometry.Shapes` from
// `Geometry//Shapes/ThreeSides`, even though the name path is identical.
namespace Shapes;

// This requires the above 'namespace Shapes' declaration. It cannot use
// `Geometry.Shapes` from `Geometry//Shapes/ThreeSides`.
struct Shapes.Square { ... };

Aliasing

Carbon's alias keyword will support aliasing namespaces. For example, this would be valid code:

namespace Timezones.Internal;
alias TI = Timezones.internal;

struct TI.RawData { ... }
fn ParseData(TI.RawData data);

Caveats

Package and library name conflicts

Library name conflicts should not occur, because it's expected that a given package is maintained by a single organization. It's the responsibility of that organization to maintain unique library names within their package.

A package name conflict occurs when two different packages use the same name, such as two packages named Stats. Versus libraries, package name conflicts are more likely because two organizations may independently choose identical names. We will encourage a unique package naming scheme, such as maintaining a name server for open source packages. Conflicts can also be addressed by renaming one of the packages, either at the source, or as a local modification.

We do need to address the case of package names conflicting with other entity names. It's possible that a pre-existing api entity will conflict with a new import, and that the api is infeasible to rename due to existing callers. Alternately, the api entity may be using an idiomatic name that it would contradict naming conventions to rename. In either case, this conflict may exist in a single file without otherwise affecting users of the API. This will be addressed by name lookup.

Potential refactorings

These are potential refactorings that we consider important to make it easy to automate.

Update imports

Imports will frequently need to be updated as part of refactorings.

When code is deleted, it should be possible to parse the remaining code, parse the imports, and determine which entities in imports are referred to. Unused imports can then be removed.

When code is moved, it's similar to deletion in the originating file. For the destination file, the moved code should be parsed to determine which entities it referred to from the originating file's imports, and these will need to be included in the destination file: either reused if already present, or added.

When new code is added, existing imports can be checked to see if they provide the symbol in question. There may also be heuristics which can be implemented to check build dependencies for where imports should be added from, such as a database of possible entities and their libraries. However, adding references may require manually adding imports.

Between api and impl files

• Move an implementation of an API from an api file to an impl file, while leaving a declaration behind.

  • This should be a local change that will not affect any calling code.
  • Inlining will be affected because the implementation won't be visible to callers.
  • Update imports.

• Split an api and impl file.

  • This is a repeated operation of individual API moves, as noted above.

• Move an implementation of an API from an impl file to an api file.

  • This should be a local change that will not affect any calling code.
  • Inlining will be affected because the implementation becomes visible to callers.
  • Update imports.

• Combine an api and impl file.

  • This is a repeated operation of individual API moves, as noted above.

• Remove the api label from a declaration.

  • Search for library-external callers, and fix them first.

• Add the api label to a declaration.

  • This should be a local change that will not affect any calling code.

• Move a non-api-labeled declaration from an api file to an impl file.

  • The declaration must be moved to the same file as the implementation of the declaration.
  • The declaration can only be used by the impl file that now contains it. Search for other callers within the library, and fix them first.
  • Update imports.

• Move a non-api-labeled declaration from an impl file to an api file.

  • This should be a local change that will not affect any calling code.
  • Update imports.

• Move a declaration and implementation from one impl file to another.

  • Search for any callers within the source impl file, and either move them too, or fix them first.
  • Update imports.

Other refactorings

• Rename a package.

  • The imports of all calling files must be updated accordingly.
  • All call sites must be changed, as the package name changes.
  • Update imports.

• Move an api-labeled declaration and implementation between different packages.

  • The imports of all calling files must be updated accordingly.
  • All call sites must be changed, as the package name changes.
  • Update imports.

• Move an api-labeled declaration and implementation between libraries in the same package.

  • The imports of all calling files must be updated accordingly.
  • As long as the namespaces remain the same, no call sites will need to be changed.
  • Update imports.

• Rename a library.

  • This is equivalent to a repeated operation of moving an api-labeled declaration and implementation between libraries in the same package.

• Move a declaration and implementation from one namespace to another.

  • Ensure the new namespace is declared for the declaration and implementation.
  • Update the namespace used by call sites.
  • The imports of all calling files may remain the same.

• Rename a namespace.

  • This is equivalent to a repeated operation of moving a declaration and implementation from one namespace to another.

• Rename a file, or move a file between directories.

  • Build configuration will need to be updated.
  • This additionally requires the steps to rename a library, because library names must correspond to the renamed paths.

Preference for few child namespaces

We expect that most code should use a package and library, but avoid specifying namespaces beneath the package. The package name itself should typically be sufficient distinction for names.

Child namespaces create longer names, which engineers will dislike typing. Based on experience, we expect to start seeing aliasing even at name lengths around six characters long. With longer names, we should expect more aliasing, which in turn will reduce code readability because more types will have local names.

We believe it's feasible for even large projects to collapse namespaces down to a top level, avoiding internal tiers of namespaces.

We understand that child namespaces are sometimes helpful, and will robustly support them for that. However, we will model code organization to encourage fewer namespaces.

Redundant markers

We use a few possibly redundant markers for packages and libraries:

• The package keyword requires one of api and impl, rather than excluding either or both.
• The filename repeats the api versus impl choice.
• The import keyword requires the full library.

These choices are made to assist human readability and tooling:

• Being explicit about imports creates the opportunity to generate build dependencies from files, rather than having them maintained separately.
• Being explicit about api versus impl makes it easier for both humans and tooling to determine what to expect.
• Repeating the type in the filename makes it possible to check the type without reading file content.
• Repeating the type in the file content makes non-file-system-based builds possible.

Open questions

These open questions are expected to be revisited by future proposals.

Different file extensions

Currently, we're using .carbon and .impl.carbon. In the future, we may want to change the extension, particularly because Carbon may be renamed.

There are several other possible extensions / commands that we've considered in coming to the current extension:

• .carbon: This is an obvious and unsurprising choice, but also quite long for a file extension.
• .6c: This sounds a little like 'sexy' when read aloud.
• .c6: This seems a weird incorrect ordering of the atomic number and has a bad, if obscure, Internet slang association.
• .cb or .cbn: These collide with several acronyms and may not be especially memorable as referring to Carbon.
• .crb: This has a bad Internet slang association.

Imports from other languages

Currently, we do not support cross-language imports. In the future, we will likely want to support imports from other languages, particularly for C++ interoperability.

Although we're not designing this right now, it could fit into the proposed syntax. For example:

import Cpp file("myproject/myclass.h");

fn MyCarbonCall(Cpp.MyProject.MyClass x);

Imports from URLs

Currently, we don't support any kind of package management with imports. In the future, we may want to support tagging imports with a URL that identifies the repository where that package can be found. This can be used to help drive package management tooling and to support providing a non-name identity for a package that is used to enable handling conflicted package names.

Although we're not designing this right now, it could fit into the proposed syntax. For example:

import Carbon library "Utilities"
    url("https://github.com/carbon-language/carbon-libraries");

Test file type

Similar to api and impl, we may eventually want a type like test. This should be part of a larger testing plan.

Alternatives

Packages

Name paths for package names

Right now, we only allow a single identifier for the package name. We could allow a full name path without changing syntax.

Advantages:

• Allow greater flexibility and hierarchy for related packages, such as Database.Client and Database.Server.
• Would allow using GitHub repository names as package names. For example, carbon-language/carbon-lang could become carbon_language.carbon_lang.

Disadvantages:

• Multiple identifiers is more complex.
• Other languages with similar distribution packages don't have a hierarchy, and so it may be unnecessary for us.
  • In other languages that use packages for distribution, they apply similar restrictions. For example, Node.JS/NPM, Python PyPi, or Rust Crates.
  • In Rust Crates, we can observe an example winapi-build and winapi-util.
• We can build a custom system for reserving package names in Carbon.

At present, we are choosing to use single-identifier package names because of the lack of clear advantage towards a more complex name path.

Referring to the package as package

Right now, we plan to refer to the package containing the current file by name. What's important in the below example is the use of Math.Stats:

package Math library "Stats" api;
api struct Stats { ... }
struct Quantiles {
  fn Stats();
  fn Build() {
    ...
    var Math.Stats b;
    ...
  }
}

We could instead use package as an identifier within the file to refer to the package, giving package.Stats.

It's important to consider how this behaves for impl files, which expect an implicit import of the API. In other words, for impl files, this can be compared to an implicit import Math; versus an implicit import Math as package;. However, there may also be explicit imports from the package, such as import Math library "Trigonometry";, which may or may not be referable to using package, depending on the precise option used.

Advantages:

• Gives a stable name to refer to the current library's package.
  • This reduces the amount of work necessary if the current library's package is renamed, although imports and library consumers may still need to be updated. If the library can also refer to the package by the package name, even with imports from other libraries within the package, work may not be significantly reduced.
• The same syntax can be used to refer to entities with the same name as the package.
  • For example, in a package named DateTime, package.DateTime is unambiguous, whereas DateTime.DateTime could be confusing.

Disadvantages:

• We are likely to want a more fine-grained, file-level approach proposed by name lookup.
• Allows package owners to name their packages things that they rarely type, but that importers end up typing frequently.
  • The existence of a short package keyword shifts the balance for long package names by placing less burden on the package owner.
• Reuses the package keyword with a significantly different meaning, changing from a prefix for the required declaration at the top of the file, to an identifier within the file.
  • We don't need to have a special way to refer to the package to disambiguate duplicate names. In other words, there is likely to be other syntax for referring to an entity DateTime in the package DateTime.
  • Renaming to a library keyword has been suggested to address concerns with package. Given that library is an argument to package, it does not significantly change the con.
• Creates inconsistencies as compared to imports from other packages, such as package Math; import Geometry;, and imports from the current package, such as package Math; import Math library "Stats";.
  • Option 1: Require package to be used to refer to all imports from Math, including the current file. This gives consistent treatment for the Math package, but not for other imports. In other words, developers will always write package.Stats from within Math, and Math.Stats will only be written in other packages.
  • Option 2: Require package be used for the current library's entities, but not other imports. This gives consistent treatment for imports, but not for the Math package as a whole. In other words, developers will only write package.Stats when referring to the current library, whether in api or impl files. Math.Stats will be used elsewhere, including from within the Math package.
  • Option 3: Allow either package or the full package name to refer to the current package. This allows code to say either package or Math, with no enforcement for consistency. In other words, both package.Stats and Math.Stats are valid within the Math package.

Because name lookup can be expected to address the underlying issue differently, we will not add a feature to support name lookup. We also don't want package owners to name their packages things that even they find difficult to type. As part of pushing library authors to consider how their package will be used, we require them to specify the package by name where desired.

Remove the library keyword from package and import

Right now, we have syntax such as:

package Math library "Median" api;
package Math library "Median" namespace Stats api;
import Math library "Median";

We could remove library, resulting in:

package Math.Median api;
package Math.Median namespace Math.Stats api;
import Math.Median;

Advantages:

• Reduces redundant syntax in library declarations.
  • We expect libraries to be common, so this may add up.

Disadvantages:

• Reduces explicitness of package vs library concepts.
• Creates redundancy of the package name in the namespace declaration.
  • Instead of package Math.Median namespace Math.Stats, could instead use Stats, or this.Stats to elide the package name.
• Potentially confuses the library names, such as Math.Median, with namespace names, such as Math.Stats.
• Either obfuscates or makes it difficult to put multiple libraries in the top-level namespace.
  • This is important because we are interested in encouraging such behavior.
  • For example, if package Math.Median api; uses the Math namespace, the presence of Median with the same namespace syntax obfuscates the actual namespace.
  • For example, if package Math.Median namespace Math api is necessary to use the Math namespace, requiring the namespace keyword makes it difficult to put multiple libraries in the top-level namespace.

As part of avoiding confusion between libraries and namespaces, we are declining this alternative.

Rename package concept

In other languages, a "package" is equivalent to what we call the name path here, which includes the namespace. We may want to rename the package keyword to avoid conflicts in meaning.

Alternative names could be 'bundle', 'universe', or something similar to Rust's 'crates'; perhaps 'compound' or 'molecule'.

Advantages:

• Avoids conflicts in meaning with other languages.
  • Java, similar to a namespace path.
  • Go, similar to a namespace path.

Disadvantages:

• The meaning of package also overlaps a fair amount, and we would lose that context.
  • Package management systems in general.
  • NPM/Node.js, as a distributable unit.
  • Python, as a distributable unit.
  • Rust, as a collection of crates.
  • Swift, as a distributable unit.

No association between the file system path and library/namespace

Several languages create a strict association between the method for pulling in an API and the path to the file that provides it. For example:

• In C++, #include refers to specific files without any abstraction.
  • For example, #include "PATH/TO/FILE.h" means there's a file PATH/TO/FILE.h.
• In Java, package and import both reflect file system structure.
  • For example, import PATH.TO.FILE; means there's a file PATH/TO/FILE.java.
• In Python, import requires matching file system structure.
  • For example, import PATH.TO.FILE means there's a file PATH/TO/FILE.py.
• In TypeScript, import refers to specific files.
  • For example, import {...} from 'PATH/TO/FILE'; means there's a file PATH/TO/FILE.ts.

For contrast:

• In Go, package uses an arbitrary name.
  • For example, import "PATH/TO/NAME" means there is a directory PATH/TO that contains one or more files starting with package NAME.

In Carbon, we are using a strict association to say that import PACKAGE library "PATH/TO/LIBRARY" means there is a file PATH/TO/LIBRARY.carbon under some package root.

Advantages:

• The strict association makes it harder to move names between files without updating callers.
• If there were a strict association of paths, it would also need to handle file system dependent casing behaviors.
  • For example, on Windows, project.carbon and Project.carbon are conflicting filenames. This is exacerbated by paths, wherein a file config and a directory Config/ would conflict, even though this would be a valid structure on Unix-based filesystems.

Disadvantages:

• A strict association between file system path and import path makes it easier to find source files. This is used by some languages for compilation.
• Allows getting rid of the package keyword by inferring related information from the file system path.

We are choosing to have some association between the file system path and library for API files to make it easier to find a library's files. We are not getting rid of the package keyword because we don't want to become dependent on file system structures, particularly as it would increase the complexity of distributed builds.

Libraries

Allow exporting namespaces

We propose to not allow exporting namespaces as part of library APIs. We could either allow or require exporting namespaces. For example:

package Checksums;

api namespace Sha256;

While this approach would mainly be syntactic, a more pragmatic use of this would be in refactoring. It implies that an aliased namespace could be marked as an api. For example, the below could be used to share an import's full contents:

package Translator library "Interface" api;

import Translator library "Functions" as TranslatorFunctions;

api alias Functions = TranslatorFunctions;

Advantages:

• Avoids any inconsistency in how entities are handled.
• Reinforces whether a namespace may contain api entities.
• Enables new kinds of refactorings.

Disadvantages:

• Creates extra syntax for users to remember, and possibly forget, when declaring api entities.
  • Makes it possible to have a namespace marked as api that doesn't contain any api entities.
• Allowing aliasing of entire imports makes it ambiguous which entities are being passed on through the namespace.
  • This may impair refactoring.
  • This can be considered related to broader imports, either all names or arbitrary code.

This alternative is declined because it's not sufficiently clear it'll be helpful, versus impairment of refactoring.

Allow importing implementation files from within the same library

The current proposal is that implementation files in a library implicitly import their API, and that they cannot import other implementation files in the same library.

We could instead allow importing implementation files from within the same library. There are two ways this could be done:

• We could add a syntax for importing symbols from other files in the same library. This would make it easy to identify a directed acyclic graph between files in the library. For example:

  package Geometry;
  
  import file("point.6c");
  

• We could automatically detect when symbols from elsewhere in the library are referenced, given an import of the same library. For example:

  package Geometry;
  
  import this;
  

Advantages:

• Allows more separation of implementation between files within a library.

Disadvantages:

• Neither approach is quite clean:
  • Using filenames creates a common case where filenames must be used, breaking away from name paths.
  • Detecting where symbols exist may cause separate parsing, compilation debugging, and compilation parallelism problems.
• Libraries are supposed to be small, and we've chosen to only allow one API file per library to promote that concept. Encouraging implementation files to be inter-dependent appears to support a more complex library design again, and may be better addressed through inter-library ACLs.
• Loses some of the ease-of-use that some other languages have around imports, such as Go.
• Part of the argument towards api and impl, particularly with a single api, has been to mirror C++ .h and .cc. Wherein a .cc #include-ing other .cc files is undesirable, allowing a impl to import another impl could be considered similarly.

The problems with these approaches, and encouragement towards small libraries, is how we reach the current approach of only importing APIs, and automatically.

Alternative library separators and shorthand

Examples are using / to separator significant terms in library names, and // to separate the package name in shorthand. For example, package Time library "Timezones/Internal"; with shorthand Time//Timezones/Internal.

Note that, because the library is an arbitrary string and shorthand is not a language semantic, this won't affect much. However, users should be expected to treat examples as best practice.

We could instead use . for library names and / for packages, such as Time/Timezones.Internal.

Advantages:

• Clearer distinction between the package and library, increasing readability.
• We have chosen not to enforce file system paths in order to ease refactoring, and encouraging a mental model where they may match could confuse users.

Disadvantages:

• Uses multiple separators, so people need to type different characters.
• There is a preference for thinking of libraries like file system paths, even if they don't actually correspond.

People like /, so we're going with /.

Single-word libraries

We could stick to single word libraries in examples, such as replacing library "Algorithms/Distance" with library "Distance".

Advantages:

• Encourages short library names.

Disadvantages:

• Users are likely to end up doing some hierarchy, and we should address it.
  • Consistency will improve code understandability.

We might list this as a best practice, and have Carbon only expose libraries following it. However, some hierarchy from users can be expected, and so it's worthwhile to include a couple examples to nudge users towards consistency.

Collapse API and implementation file concepts

We could remove the distinction between API and implementation files.

Advantages:

• Removing the distinction between API and implementation would be a language simplification.
• Developers will not need to consider build performance impacts of how they are distributing code between files.

Disadvantages:

• Serializes compilation across dependencies.
  • May be exacerbated because developers won't be aware of when they are adding a dependency that affects imports.
  • In large codebases, it's been necessary to abstract out API from implementation in languages that similarly consolidate files, such as Java. However, the lack of language-level support constrains potential benefit and increases friction for a split.
• Whereas an api/impl hierarchy gives a structure for compilation, if there are multiple files we will likely need to provide a different structure, perhaps explicit file imports, to indicate intra-library compilation dependencies.
  • We could also effectively concatenate and compile a library together, reducing build parallelism options differently.
• Makes it harder for users to determine what the API is, as they must read all the files.

Requiring users to manage the api/impl split allows us to speed up compilation for large codebases. This is important for large codebases, and shouldn't directly affect small codebases that choose to only use api files.

Automatically generating the API separation

We could try to address the problems with collapsing API and implementation files by automatically generating an API file from the input files for a library.

For example, it may preprocess files to split out an API, reducing the number of imports propagated for actual APIs. For example:

1. Extract api declarations within the api file.
2. Remove all implementation bodies.
3. Add only the imports that are referenced.

Even under the proposed model, compilation will do some of this work as an optimization. However, determining which imports are referenced requires compilation of all imports that may be referenced. When multiple libraries are imported from a single package, it will be ambiguous which imports are used until all have been compiled. This will cause serialization of compilation that can be avoided by having a developer split out the impl, either manually or with developer tooling.

The impl files may make it easier to read code, but they will also allow for better parallelism than api files alone can. This does not mean the compiler will or will not add optimizations -- it only means that we cannot wholly rely on optimizations by the compiler.

Automatically generating the API separation would only partly mitigate the serialization of compilation caused by collapsing file and library concepts. Most of the build performance impact would still be felt by large codebases, and so the mitigation does not significantly improve the alternative.

Collapse file and library concepts

We could collapse the file and library concepts. What this implies is:

• Collapse API and implementation file concepts.
  • As described there, this approach significantly reduces the ability to separate compilation.
• Only support having one file per library.
  • The file would need to contain both API and implementation together.

This has similar advantages and disadvantages to collapse API and implementation file concepts. Differences follow.

Advantages:

• Offers a uniformity of language usage.
  • Otherwise, some developers will use only api files, while others will always use impl files.
• The structure of putting API and implementation in a single file mimics other modern languages, such as Java.
• Simplifies IDEs and refactoring tools.
  • Otherwise, these systems will need to understand the potential for separation of interface from implementation between multiple files.
  • For example, see potential refactorings.

Disadvantages:

• Avoids the need to establish a hierarchy between files in a library, at the cost of reducing build parallelism options further.
• While both API and implementation is in the same file, it can be difficult to visually identify the API when it's mixed with a lengthy implementation.

As with collapse API and implementation file concepts, we consider the split to be important for large codebases. The additional advantages of a single-file restriction do not outweigh the disadvantages surrounding build performance.

Collapse the library concept into packages

We could only have packages, with no libraries. Some other languages do this; for example, in Node.JS, a package is often similar in size to what we currently call a library.

If packages became larger, that would lead to compile-time bottlenecks. Thus, if Carbon allowed large packages without library separation, we would undermine our goals for fast compilation. Even if we combined the concepts, we should expect it's by turning the "package with many small libraries" concept into "many small packages".

Advantages:

• Simplification of organizational hierarchy.
  • Less complexity for users to think about on imports.

Disadvantages:

• Coming up with short, unique package names may become an issue, leading to longer package names that overlap with the intent of libraries.
  • These longer package names would need to be used to refer to contained entities in code, affecting brevity of Carbon code. The alternative would be to expect users to always rename packages on import; some organizations anecdotally see equivalent happen for C++ once names get longer than six characters.
  • For example, boost could use per-repository packages like BoostGeometry and child libraries like algorithms-distance under the proposed approach. Under the alternative approach, it would use either a monolithic package that could create compile-time bottlenecks, or packages like BoostGeometryAlgorithmsDistance for uniqueness.
• While a package manager will need a way to specify cross-package version compatibility, encouraging a high number of packages puts more weight and maintenance cost on the configuration.
  • We expect libraries to be versioned at the package-level.

We prefer to keep the library separation to enable better hierarchy for large codebases, plus encouraging small units of compilation. It's still possible for people to create small Carbon packages, without breaking it into multiple libraries.

Collapse the package concept into libraries

Versus collapse the library concept into packages, we could have libraries without packages. Under this model, we still have libraries of similar granularity as what's proposed. However, there is no package grouping to them: there are only libraries which happen to share a namespace.

References to imports from other top-level namespaces would need to be prefixed with a '.' in order to make it clear which symbols were from imports.

For example, suppose Boost is a large system that cannot be distributed to users in a single package. As a result, Random functionality is in its own distribution package, with multiple libraries contained. The difference between approaches looks like:

• package vs library:
  • Trivial:
    • Proposal: package BoostRandom;
    • Alternative: library "Boost/Random" namespace Boost;
  • Multi-layer library:
    • Proposal: package BoostRandom library "Uniform";
    • Alternative: library "Boost/Random.Uniform" namespace Boost;
  • Specifying namespaces:
    • Proposal: package BoostRandom namespace Distributions;
    • Alternative: library "Boost/Random.Uniform" namespace Boost.Random.Distributions;
  • Combined:
    • Proposal: package BoostRandom library "Uniform" namespace Distributions;
    • Alternative: library "Boost/Random.Uniform" namespace Boost.Random.Distributions;
• import changes:
  • Trivial:
    • Proposal: import BoostRandom;
    • Alternative: import "Boost/Random";
  • Multi-layer library:
    • Proposal: import BoostRandom library "Uniform";
    • Alternative: import "Boost/Random.Uniform";
  • Namespaces have no effect on import under both approaches.
• Changes to use an imported entity:
  • Proposal: BoostRandom.UniformDistribution
  • Alternative:
    • If the code is in the Boost.Random namespace: Uniform
    • If the code is in the Boost package but a different namespace: Random.Uniform
    • If the code is outside the Boost package: .Boost.Random.Uniform

We assume that the compiler will enforce that the root namespace must either match or be a prefix of the library name, followed by a / separator. For example, Boost in the namespace Boost.Random.Uniform must either match a library "Boost" or prefix as library "Boost/..."; library "BoostRandom" does not match because it's missing the / separator.

There are several approaches which might remove this duplication, but each has been declined due to flaws:

• We could have library "Boost/Random.Uniform"; imply namespace Boost. However, we want name paths to use things listed as identifiers in files. We specifically do not want to use strings to generate identifiers in order to support understandability of code.
• We could alternately have namespace Boost; syntax imply library "Boost" namespace Boost;.
  • This approach only helps with single-library namespaces. While this would be common enough that a special syntax would help some developers, we are likely to encourage multiple libraries per namespace as part of best practices. We would then expect that the quantity of libraries in multi-library namespaces would dominate cost-benefit, leaving this to address only an edge-case of duplication issues.
  • This would create an ambiguity between the file-level namespace and other namespace keyword use. We could then rename the namespace argument for library to something like file-namespace.
  • It may be confusing as to what namespace Boost.Random; does. It may create library "Boost/Random" because library "Boost.Random" would not be legal, but the change in characters may in turn lead to developer confusion.
    • We could change the library specification to use . instead of / as a separator, but that may lead to broader confusion about the difference between libraries and namespaces.

Advantages:

• Avoids introducing the "package" concept to code and name organization.
  • Retains the key property that library and namespace names have a prefix that is intended to be globally unique.
  • Avoids coupling package management to namespace structure. For example, it would permit a library collection like Boost to be split into multiple repositories and multiple distribution packages, while retaining a single top-level namespace.
• The library and namespace are pushed to be more orthogonal concepts than packages and namespaces.
  • Although some commonality must still be compiler-enforced.
• For the common case where packages have multiple libraries, removing the need to specify both a package and library collapses two keywords into one for both import and package.
• It makes it easier to draw on C++ intuitions, because all the concepts have strong counterparts in C++.
• The prefix . on imported name paths can help increase readability by making it clear they're from imports, so long as those imports aren't from the current top-level namespace.
• Making the . optional for imports from the current top-level namespace eliminates the boilerplate character when calling within the same library.

Disadvantages:

• The use of a leading . to mark absolute paths may conflict with other important uses, such as designated initializers and named parameters.
• Declines an opportunity to align code and name organization with package distribution.
  • Alignment means that if a developer sees package BoostRandom library "Uniform";, they know installing a package BoostRandom will give them the library. Declining this means that users seeing library "Boost/Random.Uniform", they will still need to do research as to what package contains Boost/Random.Uniform to figure out how to install it because that package may not be named Boost.
  • Package distribution is a project goal, and cannot be avoided indefinitely.
  • This also means multiple packages may contribute to the same top-level namespace, which would prevent things like tab-completion in IDEs from producing cache optimizations based on the knowledge that modified packages cannot add to a given top-level namespace. For example, the ability to load less may improve performance:
    • As proposed, a package BoostRandom only adds to a namespace of the same name. If a user is editing libraries in a package BoostCustom, then BoostRandom may be treated as unmodifiable. An IDE could optimize cache invalidation of BoostRandom at the package level. As a result, if a user types BoostRandom. and requests a tab completion, the system need only ensure that libraries from the BoostRandom. package are loaded for an accurate result.
    • Under this alternative, a library Boost.Random similarly adds to the namespace Boost. However, if a user is editing libraries, the IDE needs to support them adding to both Boost and MyProject simultaneously. As a result, if a user types Boost. and requests a tab completion, the system must have all libraries from all packages loaded for an accurate result.
    • Although many features can restricted to current imports, some features, such as auto-imports, examine possible imports. Large codebases may have a memory-constrained quantity of possible imports.
• The string prefix enforcement between library and namespace forces duplication between both, which would otherwise be handled by package.
• For the common case of packages with a matching namespace name, increases verbosity by requiring the namespace keyword.
• The prefix . on imported name paths will be repeated frequently through code, increasing overall verbosity, versus the package approach which only affects import verbosity.
• Making the . optional for imports from the current top-level namespace hides whether an API comes from the current library or an import.

We are declining this approach because we desire package separation, and because of concerns that this will lead to an overall increase in verbosity due to the preference for few child namespaces, whereas this alternative benefits when namespace is specified more often.

Different file type labels

We're using api and impl for file types, and have test as an open question.

We've considered using interface instead of api, but that introduces a terminology collision with interfaces in the type system.

We've considered dropping api from naming, but that creates a definition from absence of a keyword. It also would be more unusual if both impl and test must be required, that api would be excluded. We prefer the more explicit name.

We could spell out impl as implementation, but are choosing the abbreviation for ease of typing. We also don't think it's an unclear abbreviation.

We expect impl to be used for implementations of interface. This isn't quite as bad as if we used interface instead of api because of the api export syntax on entities, such as api fn DoSomething(), which could create ambiguities as interface fn DoSomething(). It may still confuse people to see an interface impl in an api file. However, we're touching on related concepts and don't see a great alternative.

Function-like syntax

We could consider more function-like syntax for import, and possibly also package.

For example, instead of:

import Math library "Stats";
import Algebra as A;

We could do:

import("Math", "Stats").Math;
alias A = import("Algebra").Algebra;

Or some related variation.

Advantages:

• Allows straightforward reuse of alias for language consistency.
• Easier to add more optional arguments, which we expect to need for interoperability and URLs.
• Avoids defining keywords for optional fields, such as library.
  • Interoperability and package management may add more fields long-term.

Disadvantages:

• It's unusual for a function-like syntax to produce identifiers for name lookup.
  • This could be addressed by requiring alias, but that becomes verbose.
  • There's a desire to explicitly note the identifier being imported some way, as with .Math and .Algebra above. However, this complicates the resulting syntax.

The preference is for keywords.

Inlining from implementation files

An implicit reason for keeping code in an api file is that it makes it straightforward to inline code from there into callers.

We could explicitly encourage inlining from impl files as well, making the location of code unimportant during compilation. Alternately, we could add an inline file type which explicitly supports separation of inline code from the api file.

Advantages:

• Allows moving code out of the main API file for easier reading.

Disadvantages:

• Requires compilation of impl files to determine what can be inlined from the api file, leading to the transitive closure dependency problems which impl files are intended to avoid.

We expect to only support inlining from api files in order to avoid confusion about dependency problems.

Library-private access controls

We currently have no special syntax for library-private APIs. However, non-exported APIs are essentially library-private, and may be in the api file. It's been suggested that we could either provide a special syntax or a new file type, such as shared_impl, to support library-private APIs.

Advantages:

• Allows for better separation of library-private APIs.

Disadvantages:

• Increases language complexity.
• Dependencies are still an issue for library-private APIs.
  • If used from the api file, the dependencies are still in the transitive closure of client libraries, and any separation may confuse users about the downsides of the extra dependencies.
  • If only used from impl files, then they could be in the impl file if there's only one, or shared from a separate library.
• Generalized access controls may provide overlapping functionality.

At this point in time, we prefer not to provide specialized access controls for library-private APIs.

Managing API versus implementation in libraries

At present, we plan to have api versus impl as a file type, and also .carbon versus .impl.carbon as the file extension. We chose to use both together, rather than one or the other, because we expect some parties to strongly want file content to be sufficient for compilation, while others will want file extensions to be meaningful for the syntax split.

Instead of the file type split, we could drift further and instead have APIs in any file in a library, using the same kind of API markup.

Advantages:

• May help users who have issues with cyclical code references.
• Improves compiler inlining of implementations, because the compiler can decide how much to actually put in the generated API.

Disadvantages:

• While allowing users to spread a library across multiple files can be considered an advantage, we see the single API file as a way to pressure users towards smaller libraries, which we prefer.
• May be slower to compile because each file must be parsed once to determine APIs.
• For users that want to see only APIs in a file, they would need to use tooling to generate the API file.
  • Auto-generated documentation may help solve this problem.

Multiple API files

The proposal also presently suggests a single API file. Under an explicit API file approach, we could still allow multiple API files.

Advantages:

• More flexibility when writing APIs; could otherwise end up with one gigantic API file.

Disadvantages:

• Encourages larger libraries by making it easier to provide large APIs.
• Removes some of the advantages of having an API file as a "single place" to look, suggesting more towards the markup approach.
• Not clear if API files should be allowed to depend on each other, as they were intended to help resolve cyclical dependency issues.

We particularly want to discourage large libraries, and so we're likely to retain the single API file limit.

Name paths as library names

We're proposing strings for library names. We've discussed also using name paths (My.Library) and also restricting to single identifiers (Library).

Advantages:

• Shares the form between packages (identifiers) and namespaces (name paths).
• Enforces a constrained set of names for libraries for cross-package consistency of naming.

Disadvantages:

• Indicates that a library may be referred to in code, when only the package and namespace are used for name paths of entities.
• The constrained set of names may also get in the way for some packages that can make use of more flexibility in naming.

We've decided to use strings primarily because we want to draw the distinction that a library is not something that's used when referring to an entity in code.

Imports

Block imports

Rather than requiring an import keyword per line, we could support block imports, as can be found in languages like Go.

In other words, instead of:

import Math;
import Geometry;

We could have:

imports {
  Math,
  Geometry,
}

Advantages:

• Allows repeated imports with less typing.

Disadvantages:

• Makes it harder to find files importing a package or library using tools like grep.

One concern has been that a mix of import and imports syntax would be confusing to users: we should only allow one.

This alternative has been declined because retyping import statements is low-cost, and grep is useful.

Block imports of libraries of a single package

We could allow block imports of libraries from the same package. For example:

import Containers libraries({
  "FlatHashMap",
  "FlatHashSet",
})

The result of this api alias allowing Containers.HashSet() to work regardless of whether HashSet is in "HashContainers" or "Internal" may be clearer if both import Containers statements were a combined import Containers libraries({"HashContainers", "Internal"});.

The advantages/disadvantages are similar to block imports. Additional advantages/disadvantages are:

Advantages:

• If we limit to one import per library, then any alias of the package Containers is easier to understand as affecting all libraries.

Disadvantages:

• If we allow both library and libraries syntax, it's two was of doing the same thing.
  • Can be addressed by always requiring libraries, removing library, but that diverges from package's library syntax.

This alternative has been declined for similar reasons to block imports; the additional advantages/disadvantages don't substantially shift the cost-benefit argument.

Broader imports, either all names or arbitrary code

Carbon imports require specifying individual names to import. We could support broader imports, for example by pulling in all names from a library. In C++, the #include preprocessor directive even supports inclusion of arbitrary code. For example:

import Geometry library "Shapes" names *;

// Triangle was imported as part of "*".
fn Draw(Triangle x) { ... }

Advantages:

• Reduces boilerplate code specifying individual names.

Disadvantages:

• Loses out on parser benefits of knowing which identifiers are being imported.
• Increases the risk of adding new features to APIs, as they may immediately get imported by a user and conflict with a pre-existing name, breaking code.
• As the number of imports increases, it can become difficult to tell which import a particular symbol comes from, or how imports are being used.
• Arbitrary code inclusion can result in unexpected code execution, a way to create obfuscated code and a potential security risk.

We particularly value the parser benefits of knowing which identifiers are being imported, and so we require individual names for imports.

Direct name imports

We could allow direct imports of names from libraries. For example, under the current setup we might see:

import Math library "Stats";
alias Median = Stats.Median;
alias Mean = Stats.Mean;

We could simplify this syntax by augmenting import:

import Math library "Stats" name Median;
import Math library "Stats" name Mean;

Or more succinctly with block imports of names:

import Math library "Stats" names {
  Median,
  Mean,
}

Advantages:

• Avoids an additional alias step.

Disadvantages:

• With a single name, this isn't a significant improvement in syntax.
• With multiple names, this runs into similar issues as block imports.

Optional package names

We could allow a short syntax for imports from the current library. For example, this code imports Geometry.Shapes:

package Geometry library "Operations" api;

import library "Shapes";

Advantages:

• Reduces typing.

Disadvantages:

• Makes it harder to find files importing a package or library using tools like grep.
• Creates two syntaxes for importing libraries from the current package.
  • If we instead disallow import Geometry library "Shapes" from within Geometry, then we end up with a different inconsistency.

Overall, consistent with the decision to disallow block imports, we are choosing to require the package name.

Namespaces

File-level namespaces

We are providing entity-level namespaces. This is likely necessary to support migrating C++ code, at a minimum. It's been discussed whether we should also support file-level namespaces.

For example, this is the current syntax for defining Geometry.Shapes.Circle:

package Geometry library "Shapes" api;

namespace Shapes;
struct Shapes.Circle;

This is the proposed alternative syntax for defining Geometry.Shapes.Circle, and would put all entities in the file under the Shapes namespace:

package Geometry library "Shapes" namespace Shapes api;

struct Circle;

Advantages:

• Reduces repetitive syntax in the file when every entity should be in the same, child namespace.
  • Large libraries and packages are more likely to be self-referential, and may pay a disproportionate ergonomics tax that others wouldn't see.
  • Although library authors could also avoid this repetitive syntax by omitting the namespace, that may in turn lead to more name collisions for large packages.
  • Note that syntax can already be reduced with a shorter namespace alias, but the redundancy cannot be eliminated.
• Reduces the temptation of aliasing in order to reduce verbosity, wherein it's generally agreed that aliasing creates inconsistent names which hinder readability.
  • Users are known to alias long names, where "long" may be considered anything over six characters.
  • This is a risk for any package that uses namespaces, as importers may also need to address it.

Disadvantages:

• Encourages longer namespace names, as they won't need to be retyped.
• Increases complexity of the package keyword.
• Creates two ways of defining namespaces, and reuses the namespace keyword in multiple different ways.
  • We generally prefer to provide one canonical way of doing things.
  • Does not add functionality which cannot be achieved with entity-level namespaces. However, the converse is not true: entity-level control allows a single file to put entities into multiple namespaces.
• Creates a divergence between code as written by the library maintainer and code as called.
  • Calling code would need to specify the namespace, even if aliased to a shorter name. Library code gets to omit this, essentially getting a free alias.

We are choosing not to provide this for now because we want to provide the minimum necessary support, and then see if it works out. It may be added later, but it's easier to add features than to remove them.

Scoped namespaces

Instead of including additional namespace information per-name, we could have scoped namespaces, similar to C++. For example:

namespace absl {
  namespace numbers_internal {
    fn SafeStrto32Base(...) { ... }
  }

  fn SimpleAtoi(...) {
    ...
    return numbers_internal.SafeStrto32Base(...);
    ...
  }
}

Advantages:

• Makes it easy to write many things in the same namespace.

Disadvantages:

• It's not clear which namespace an identifier is in without scanning to the start of the file.
• It can be hard to find the end of a namespace. For examples addressing this, end-of-namespace comments are called for by both the Google and Boost style guides.
  • Carbon may disallow the same-line-as-code comment style used for this. Even if not, if we acknowledge it's a problem, we should address it structurally for readability.
  • This is less of a problem for other scopes, such as functions, because they can often be broken apart until they fit on a single screen.

There are other ways to address the con, such as adding syntax to indicate the end of a namespace, similar to block comments. For example:

{ namespace absl
  { namespace numbers_internal
    fn SafeStrto32Base(...) { ... }
  } namespace numbers_internal

  fn SimpleAtoi(...) {
    ...
    return numbers_internal.SafeStrto32Base(...);
    ...
  }
} namespace absl

While we could consider such alternative approaches, we believe the proposed contextless namespace approach is better, as it reduces information that developers will need to remember when reading/writing code.