From 979fe2cd899c658ba7610b3e7300eafc2960c33e Mon Sep 17 00:00:00 2001 From: Jon Meow <46229924+jonmeow@users.noreply.github.com> Date: Fri, 28 Jan 2022 18:14:31 -0800 Subject: [PATCH] Merge naming conventions #861 into the design (#1056) A pretty straight copy of #861. Cutting down README.md example text since it seemed a little redundant with examples in the bullets. --- docs/design/README.md | 32 +++----- docs/design/naming_conventions.md | 123 ++++++++++++++++++++---------- 2 files changed, 91 insertions(+), 64 deletions(-) diff --git a/docs/design/README.md b/docs/design/README.md index e7d063683a20..ea985597efc7 100644 --- a/docs/design/README.md +++ b/docs/design/README.md @@ -209,30 +209,18 @@ has not been selected yet. #### Naming conventions > References: [Naming conventions](naming_conventions.md) -> -> **TODO:** References need to be evolved. -Our current proposed naming convention are: +Our naming conventions are: -- `UpperCamelCase` for names of compile-time resolved constants, whether they - participate in the type system or not. -- `lower_snake_case` for keywords and names of run-time resolved values. - -As a matter of style and consistency, we will follow these conventions where -possible and encourage convergence. - -For example: - -- An integer that is a compile-time constant sufficient to use in the - construction a compile-time array size, such as a template function - parameter, might be named `N`. -- A generic function parameter's value can't be used during type-checking, but - might still be named `N`, since it will be a constant available to the - compiler at code generation time. -- Functions and most types will be in `UpperCamelCase`. -- A type where only run-time type information queries are available would end - up as `lower_snake_case`. -- A keyword like `import` uses `lower_snake_case`. +- For idiomatic Carbon code: + - `UpperCamelCase` will be used when the named entity cannot have a + dynamically varying value. For example, functions, namespaces, or + compile-time constant values. + - `lower_snake_case` will be used when the named entity's value won't be + known until runtime, such as for variables. +- For Carbon-provided features: + - Keywords and type literals will use `lower_snake_case`. + - Other code will use the conventions for idiomatic Carbon code. #### Aliases diff --git a/docs/design/naming_conventions.md b/docs/design/naming_conventions.md index 127a9763ec1e..ab13049bd1c3 100644 --- a/docs/design/naming_conventions.md +++ b/docs/design/naming_conventions.md @@ -10,56 +10,95 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception ## Table of contents -- [TODO](#todo) - [Overview](#overview) +- [Details](#details) + - [Constants](#constants) + - [Carbon-provided item naming](#carbon-provided-item-naming) +- [Alternatives considered](#alternatives-considered) +- [References](#references) -## TODO - -This is a skeletal design, added to support [the overview](README.md). It should -not be treated as accepted by the core team; rather, it is a placeholder until -we have more time to examine this detail. Please feel welcome to rewrite and -update as appropriate. - ## Overview -We would like to have widespread and consistent naming conventions across Carbon -code to the extent possible. This is for the same core reason as naming -conventions are provided in most major style guides. Even migrating existing C++ -code at-scale presents a significant opportunity to converge even more broadly -and we're interested in pursuing this if viable. +Our naming conventions are: -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, is: +- For idiomatic Carbon code: + - `UpperCamelCase` will be used when the named entity cannot have a + dynamically varying value. For example, functions, namespaces, or + compile-time constant values. + - `lower_snake_case` will be used when the named entity's value won't be + known until runtime, such as for variables. +- For Carbon-provided features: + - Keywords and type literals will use `lower_snake_case`. + - Other code will use the guidelines for idiomatic Carbon code. -- `UpperCamelCase` for names of compile-time resolved constants, such that - they can participate in the type system and type checking of the program. - Comple-time constants fall into two categories: - - _Template_ constants that can be used in type checking, including - literals. - - _Generic_ constants whose value is not used in type checking, but will - be used as part of code generation. -- `lower_snake_case` for names of run-time resolved values. +In other words: -As an example, an integer that is a compile-time constant sufficient to use in -the construction a compile-time array size might be named `N`, where an integer -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`. +| Item | Convention | Explanation | +| ------------------------- | ------------------ | ------------------------------------------------------------------------------------------ | +| Packages | `UpperCamelCase` | Used for compile-time lookup. | +| Types | `UpperCamelCase` | Resolved at compile-time. | +| Functions | `UpperCamelCase` | Resolved at compile-time. | +| Methods | `UpperCamelCase` | Methods, including virtual methods, are equivalent to functions. | +| Generic parameters | `UpperCamelCase` | May vary based on inputs, but are ultimately resolved at compile-time. | +| Compile-time constants | `UpperCamelCase` | Resolved at compile-time. See [constants](#constants) for more remarks. | +| Variables | `lower_snake_case` | May be reassigned and thus require runtime information. | +| Member variables | `lower_snake_case` | Behave like variables. | +| Keywords | `lower_snake_case` | Special, and developers can be expected to be comfortable with this casing cross-language. | +| Type literals | `lower_snake_case` | Equivalent to keywords. | +| Boolean type and literals | `lower_snake_case` | Equivalent to keywords. | +| Other Carbon types | `UpperCamelCase` | Behave like normal types. | +| `Self` and `Base` | `UpperCamelCase` | These are similar to type members on a class. | -We only use `UpperCamelCase` and `lower_snake_case` (skipping other variations -on both snake-case and camel-case naming conventions) because these two have the -most significant visual separation. For example, the value of adding -`lowerCamelCase` for another set seems low given the small visual difference -provided; in particular, one-word identifiers would have no difference. +We only use `UpperCamelCase` and `lower_snake_case` in naming conventions in +order to minimize the variation in rules. -The rationale for the specific division between the two isn't a huge or -fundamental concept, but it stems from a convention in Ruby where constants are -named with a leading capital letter. The idea is that it mirrors the English -language capitalization of proper nouns: the name of a constant refers to a -_specific_ value that is precisely resolved at compile time, not just to _some_ -value. For example, there are many different _shires_ in Britain, but Frodo -comes from the _Shire_ -- a specific fictional region. +## Details + +### Constants + +Consider the following code: + +```carbon +package Example; + +let CompileTimeConstant: i32 = 7; + +fn RuntimeFunction(runtime_constant: i32); +``` + +In this example, `CompileTimeConstant` has a singular value (`7`) which is known +at compile-time. As such, it uses `UpperCamelCase`. + +On the other hand, `runtime_constant` may be constant within the function body, +but it is assigned at runtime when `RuntimeFunction` is called. Its value is +only known in a given runtime invocation of `RuntimeFunction`. As such, it uses +`lower_snake_case`. + +### Carbon-provided item naming + +Carbon-provided items are split into a few categories: + +- Keywords; for example, `for`, `fn`, and `var`. +- Type literals; for example, `i`, `u`, and `f`. +- Boolean type and literals; for example, `bool`, `true`, and `false`. + - The separate categorization of booleans should not be taken as a rule + that only booleans would use lowercase; it's just the only example right + now. +- `Self` and `Base`. +- Other Carbon types; for example, `Int`, `UInt`, and `String`. + +Note that while other Carbon types currently use `UpperCamelCase`, that should +not be inferred to mean that future Carbon types will do the same. The leads +will make decisions on future naming. + +## Alternatives considered + +- [Other naming conventions](/proposals/p0861.md#other-naming-conventions) +- [Other conventions for naming Carbon types](/proposals/p0861.md#other-conventions-for-naming-carbon-types) + +## References + +- Proposal + [#861: Naming conventions](https://github.com/carbon-language/carbon-lang/pull/861)