naming_conventions.md

Naming conventions

Table of contents

• Overview
• Details
  • Constants
  • Carbon-provided item naming
• Alternatives considered
• References

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

• Other naming conventions
• Other conventions for naming Carbon types

References

• Proposal #861: Naming conventions