Table of Contents

Comments & Documentation

Document the why, not the what. Code should be self-explanatory.

XML Docs — Required on Public API

/// <summary>
/// Encode a 32-char hex string into a 128-bit GUID.
/// </summary>
/// <param name="hex">The hex string to encode.</param>
/// <returns>A GUID representation of the hex string.</returns>
/// <exception cref="InvalidOperationException">Thrown when input length is not 32.</exception>
public static Guid EncodeHexToGuid(string hex)
{
    // ...
}

Rules

Rule Scope Enforced
XML <summary> on all public members Public API Yes
XML <param> for every parameter Public methods Yes
XML <returns> for non-void returns Public methods Yes
XML <exception> for thrown exceptions Public methods Suggested
No commented-out code in new files All Yes
// TODO: for future work items All Allowed

Inline Comments

// GOOD — explains WHY
// Offset by 1 because the array is 0-indexed but IDs start at 1
var index = entityId - 1;

// BAD — restates the code
// Subtract 1 from entityId
var index = entityId - 1;

When NOT to Comment

  • Property/field names that are self-documenting
  • Standard Unity lifecycle methods (Awake, Start, Update)
  • Obvious one-liners

References