> For the complete documentation index, see [llms.txt](https://utoolkit.gamepangin.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://utoolkit.gamepangin.com/introduction/code-naming-convention.md).

# Code Naming Convention

## Code Naming Convention

* Rather than simply answering "what" or "how," comments can fill in the gaps and tell us "why."
* Use the // comment to keep the explanation next to the logic.
* Use a Tooltip instead of a comment for serialized fields.
* Avoid Regions. They encourage large class sizes. Collapsed code is more difficult to read.
* Use a link to an external reference for legal information or licensing to save space.
* Use a summary XML tag in front of public methods or functions for output documentation/Intellisense.
* Rather than simply answering "what" or "how," comments can fill in the gaps and tell us "why."
* Use the // comment to keep the explanation next to the logic.
* Use a Tooltip instead of a comment for serialized fields.
* Avoid Regions. They encourage large class sizes. Collapsed code is more difficult to read.
* Use a link to an external reference for legal information or licensing to save space.
* Use a summary XML tag in front of public methods or functions for output documentation/Intellisense.

### Naming/Casing

* Use Pascal case (e.g. ExamplePlayerController, MaxHealth, etc.) unless noted otherwise
* Use camel case (e.g. examplePlayerController, maxHealth, etc.) for local/private variables, parameters.
* Avoid snake\_case, kebab-case, Hungarian notation

### Formatting

* Choose K\&R (opening curly braces on same line) or Allman (opening curly braces on a new line) style braces.
* Keep lines short. Consider horizontal whitespace. Define a standard line width in your style guide (80-120 characters).
* Use a single space before flow control conditions, e.g. while (x == y)
* Avoid spaces inside brackets, e.g. x = dataArray\[index]
* Use a single space after a comma between function arguments.
* Don’t add a space after the parenthesis and function arguments, e.g. CollectItem(myObject, 0);
* Don’t use spaces between a function name and parenthesis, e.g. DropPowerUp(myPrefab, 0);
* Use vertical spacing (extra blank line) for visual separation.

### Comments

* Rather than simply answering "what" or "how," comments can fill in the gaps and tell us "why."
* Use the // comment to keep the explanation next to the logic.
* Use a Tooltip instead of a comment for serialized fields.
* Avoid Regions. They encourage large class sizes. Collapsed code is more difficult to read.
* Use a link to an external reference for legal information or licensing to save space.
* Use a summary XML tag in front of public methods or functions for output documentation/Intellisense.

### Namespace

* Pascal case, without special symbols or underscores.
* Add using line at the top to avoid typing namespace repeatedly.\\
* Create sub-namespaces with the dot (.) operator, e.g. MyApplication.GameFlow, [MyApplication.AI](http://MyApplication.AI), etc.

```csharp
namespace Gamepangin.StyleExample { }
```

### Enums

* Use a singular type name.
* No prefix or suffix.

```csharp
public enum Direction
{
    North,
    South,
    East,
    West
}
```

### Flags Enums

* Use a plural type name
* No prefix or suffix.
* Use column-alignment for binary values

```csharp
[Flags]
public enum AttackModes
{
    // Decimal                         // Binary
    None = 0,                          // 000000
    Melee = 1,                         // 000001
    Ranged = 2,                        // 000010
    Special = 4,                       // 000100

    MeleeAndSpecial = Melee | Special  // 000101
}
```

### Interfaces

* Name interfaces with adjective phrases.
* Use the 'I' prefix.

```csharp
public interface IDamageable
{
    string DamageTypeName { get; }
    float DamageValue { get; }

    // METHODS:
    // - Start a methods name with a verbs or verb phrases to show an action.
    // - Parameter names are camelCase.
    bool ApplyDamage(string description, float damage, int numberOfHits);
}

public interface IDamageable<T>
{
   void Damage(T damageTaken);
}
```

### Classes / Structs

* Name them with nouns or noun phrases.
* Avoid prefixes.

```csharp
public class StyleExample : MonoBehaviour { }
```

### Fields

* Avoid special characters (backslashes, symbols, Unicode characters); these can interfere with command line tools.
* Use nouns for names, but prefix booleans with a verb.
* Use meaningful names. Make names searchable and pronounceable. Don’t abbreviate (unless it’s math).
* Use camelCase.
* Add an optional underscore (*) in front of private fields to differentiate from local variables*
* *You can alternatively use more explicit prefixes: m* = member variable, s\_ = static, k\_ = const
* Specify (or omit) the default access modifier; just be consistent with your style guide.

```csharp
public bool canJump;
private int elapsedTimeInDays;

// Use [SerializeField] attribute if you want to display a private field in Inspector.
// Booleans ask a question that can be answered true or false.
[SerializeField] private bool isPlayerDead;
```

### Properties

* Preferable to a public field.
* PascalCase, without special characters.
* Use the expression-bodied properties to shorten, but choose your preferred format. e.g. use expression-bodied for read-only properties but { get; set; } for everything else.
* Use the Auto-Implemented Property for a public property without a backing field.

```csharp
// the private backing field
private int maxHealth;

// read-only, returns backing field
public int MaxHealthReadOnly => maxHealth;

// equivalent to:
// public int MaxHealth { get; private set; }

// explicitly implementing getter and setter
public int MaxHealth
{
	  get => maxHealth;
    set => maxHealth = value;
}

// write-only (not using backing field)
public int Health { private get; set; }

// write-only, without an explicit setter
public void SetMaxHealth(int newMaxValue) => maxHealth = newMaxValue;

// auto-implemented property without backing field
public string DescriptionName { get; set; } = "Fireball";
```

### Events

* Name with a verb phrase.
* Present participle means "before" and past participle mean "after."
* Use System.Action delegate for most events (can take 0 to 16 parameters).
* Define a custom EventArg only if necessary (either System.EventArgs or a custom struct). OR alternatively, use the System.EventHandler; choose one and apply consistently.
* Choose a naming scheme for events, event handling methods (subscriber/observer), and event raising methods (publisher/subject) e.g. event/action = "OpeningDoor", event raising method = "OnDoorOpened", event handling method = "MySubject\_DoorOpened"

### Methods

* Start a methods name with a verbs or verb phrases to show an action.
* Parameter names are camel case.