Naming conventions

Table of contents

Overview

Our naming conventions are:

  • 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.

In other words:

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.
Compile-time parameters UpperCamelCase May vary based on inputs, but are ultimately resolved at compile-time.
Compile-time constants UpperCamelCase Resolved at compile-time. See 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 in naming conventions in order to minimize the variation in rules.

Details

Constants

Consider the following code:

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<digits>, u<digits>, and f<digits>.
  • 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

References