Code Commenting

Good comments do two jobs for Sol:

  1. Sol-edit (or equivalent Sol markers) separate our changes from upstream / other forks when we touch shared files, which makes merges and conflict resolution sane.
  2. Normal comments explain non-obvious behaviour for the next person (including future you).

Sol markers

Add Sol markers when you edit files outside Sol-owned trees (not under _Sol). That includes stock SS14 paths and other fork folders (_Starlight, _FarHorizons, _afterlight, and similar).

Files that already live under _Sol generally do not need Sol-edit wrappers — the path already marks ownership.

Do not mark usings

Do not wrap using directives in Sol markers. Using conflicts are easy to resolve; markers only clutter them.

Regular comments

Use ordinary comments where behaviour is hard to infer — YAML that looks decorative, XAML blocks that define UI regions, C# methods / fields that need IntelliSense tooltips.

Regions in C#

Group related members with #region / #endregion. Prefer one region for methods and clear regions for fields/constants.

Comment examples

XML / XAML

<!-- Section label -->

<!--
Multi-line note
-->

<!-- Sol -->
<!-- Sol change -->
<!-- End Sol -->

YAML

# Sol
# Sol: reason for the change
someField: value
# End Sol

C#

// Sol
// Sol-edit: brief reason
DoTheThing();
// End Sol

/// <summary>
/// What this API does for callers / IntelliSense.
/// </summary>

Match the marker style already used in nearby Sol edits in that file when one exists.