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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://utoolkit.gamepangin.com/introduction/code-naming-convention.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.