Naming and Casing
Naming
When naming types, variables, properties, and functions it is important to do so in a manner that is concise, detailed, and explicit. A name should provide enough information at a glance so that you immediately understand what it is being used for and why; but, it shouldn't do so overbearingly. Some of this information in the name can be omitted if the immediate surrounding context provides it.
Comments should rarely be necessary. The naming itself should be able to carry all the information needed for external/internal use. Thus reserving comments for cases where important details can't be expressed through the variable name.
Most abbreviations should also be avoided, for example:
- Use "Average" instead of "Avg"
- Use "Minimum"/"Maximum" instead of "Min/Max"
- Use "Position" instead of "Pos"
This also extends to heavily abbreviated terms like "DeltaTime" (which is often seen as "dt"). In this case, not every developer is familiar with what this abbreviated form means (as it's not directly common outside of Game Development), so it would be better written as "deltaTime" since names should be as accessible as possible.
Following guidelines like this allows for names that are clear, explicit, and accessible: contributing significantly to a maintainable and cooperative development environment.
Casing
Variable Scope
Variables switch between PascalCase and camelCase based on what Scope they are in:
- Variables located within the Top Level Scope are always PascalCase.
- Otherwise, variables deeper than the Top Level Scope are always camelCase.
Dynamic Variables
IF a variable is intended to be written to multiple times and its value is not guaranteed to be static after initialization, an Underscore MUST be added into the name of the variable.
What is "Static after Initialization"
This is when an unset variable is initialized outside of its variable definition (e.g. within an Organizational Code Block or another process) and the variables value is not expected to change afterwards.
This modification does not have to adhere to snake_case! There must be at minimum one underscore; beyond that, it is up to complete personal preference where - and how often - you separate word boundaries with an underscore.
Why use Underscore casing for Dynamic Variables instead of Constant Variables?
Simply put, Dynamic Variables are more rare than Constant Variables. By adding an Underscore to a Dynamic Variables name, we drastically improve its visibility and distinctly indicate its dynamicity.
Types, Properties, and Functions
Types, Properties, and Functions are ALWAYS expected to use PascalCase.
The reasoning for the three of these are slightly different from the reasonings used for Variables:
- Types are treated as a foundational concept separate from the functional aspect of the programming language itself, therefore requiring elevated visibility.
- For Properties we have two reasons:
- 1. We expect Properties to be under the same restrictions as a Constant Variable.
- 2. We treat Properties as "scopeless" since they exist independently within their Data Object, unaffected by Scopes.
- Similarly, Functions also are expected to behave as a Constant Variable, and serve as an essential functional element that requires higher visibility.