​

Общие соглашения по программированию

​

Не копипастите код

​

Не используйте магические строки/числа

​

Комментарии

• Комментируйте код на высоком уровне, чтобы объяснить что код делает, и что более важно, почему код делает то, что он делает.
• При документировании классов, структур, методов, свойств/полей и членов класса используйте XML docs. DataFields и публичные методы должны быть задокументированы всегда.
  • Пример:
      /// <summary>
      /// Resets the InteractCounter on the <see cref="FooComponent"/>.
      /// </summary>
      /// <remarks>
      /// This is a public method other systems can call to interact with FooComponent!
      /// Remember that public methods should always use docstring.
      /// </remarks>
      [PublicAPI]
      public void ResetInteractCounter(Entity<FooComponent?> ent)
  

​

Почему, а не Что

​

Пример 1

var fractionalPressureChange = Atmospherics.R * (outlet.Air.Temperature / outlet.Air.Volume + inlet.Air.Temperature / inlet.Air.Volume);

// Take R and multiply it by the ratio of outlet temperature divided by outlet air volume and add it to ...
var fractionalPressureChange = Atmospherics.R * (outlet.Air.Temperature / outlet.Air.Volume + inlet.Air.Temperature / inlet.Air.Volume);

// We want moles transferred to be proportional to the pressure difference, i.e.
// dn/dt = G*P

// To solve this we need to write dn in terms of P. Since PV=nRT, dP/dn=RT/V.
// This assumes that the temperature change from transferring dn moles is negligible.
// Since we have P=Pi-Po, then dP/dn = dPi/dn-dPo/dn = R(Ti/Vi - To/Vo):
var dPdn = Atmospherics.R * (outlet.Air.Temperature / outlet.Air.Volume + inlet.Air.Temperature / inlet.Air.Volume);

​

Пример 2

if (HasComp<MindContainerComponent>(uid))
    return;

// more stuff

// Don't let players who drink cognizine be eligible for a ghost takeover
if (HasComp<MindContainerComponent>(uid))
    return;

​

Строки и идентификаторы

private void UpdateDisplay(Gender gender)
{
    // This can't be localized! And the capitalization is kinda weird!
    // Don't do this!
    GenderLabel.Text = gender.ToString();

    // This is good!
    GenderLabel.Text = Loc.GetString($"gender-{gender}");
}

​

Инвариантные сравнения человекочитаемых строк

​

Свойства

public string Name
{
    get => _name;
    private set => _name = Loc.GetString(value);
}

​

Правильный порядок членов в типе

class FooBar
{
    private int _field;

    public void Update() {
        _field *= 2;
        Counter += 1;
    }

    public int Counter { get; set; }
}

class FooBar
{
    private int _field;
    public int Counter { get; set; }

    public void Update() {
        _field *= 2;
        Counter += 1;
    }

}

​

Проектные соглашения

​

Расположение файлов

1. Начинайте с using directives в верхней части файла.
2. Все классы должны быть явно указаны в namespace. Используйте file-scoped namespaces, например один namespace Content.Server.Atmos.EntitySystems; перед определениями классов вместо namespace Content.Server.Atmos.EntitySystems { /* class here */ }.
3. Всегда размещайте все поля и авто-свойства перед любыми методами в определении класса.

​

Методы

​

Переносы строк в списках параметров/аргументов

public void CopyTo(ISerializationManager serializationManager, SortedDictionary<TKey, TValue> source, ref SortedDictionary<TKey, TValue> target,
    SerializationHookContext hookCtx, ISerializationContext? context = null)

public void CopyTo(
    ISerializationManager serializationManager,
    SortedDictionary<TKey, TValue> source,
    ref SortedDictionary<TKey, TValue> target,
    SerializationHookContext hookCtx,
    ISerializationContext? context = null)

​

Константы и CVars

• константой (const), если оно никогда не должно изменяться
• CVar, если оно должно быть настраиваемым

​

Prototypes

​

Поля данных Prototype

[DataField]
public List<ProtoId<ExamplePrototype>> ExampleTypes = new();

​

Enums vs Prototypes

​

Ресурсы

​

Звуки

[DataField]
public SoundSpecifier Sound = new SoundCollectionSpecifier("MySoundCollection");

# You can define a sound collection like this
- type: soundCollection
  id: MySoundCollection
  files:
  - /Audio/Effects/Cargo/ping.ogg

# And use it like this
- type: MyComponent
  sound:
    collection: MySoundCollection

​

Спрайты и текстуры

[DataField]
public SpriteSpecifier Icon = SpriteSpecifier.Invalid;

# You can specify a specific texture file like this, /Textures/ is optional
- type: MyComponent
  icon: /Textures/path/to/my/texture.png

# /Textures/ is optional and will be automatically inferred, however make sure that you don't start the path with a slash if you don't specify it
- type: MyComponent
  icon: path/to/my/texture.png

# You can specify an rsi sprite like this
- type: MyOtherComponent
  icon:
    sprite: /Textures/path/to/my/sprite.rsi
    state: MySpriteState

{
    "version": 1,
    "license": "CC-BY-SA-3.0",
    "copyright": "Taken from tgstation at commit https://github.com/tgstation/tgstation/commit/547852588166c8e091b441e4e67169e156bb09c1",
    "size": {
        "x": 32,
        "y": 32
    },
    "states": [
        {
            "name": "icon"
        },
        {
            "name": "equipped-BACKPACK",
            "directions": 4
        },
        {
            "name": "inhand-left",
            "directions": 4
        },
        {
            "name": "inhand-right",
            "directions": 4
        }
    ]
}

​

EntityUid в логах

// If you're in an entity system...
_adminLogs.Add(LogType.MyLog, LogImpact.Medium, $"{ToPrettyString(uid)} did something!");

// If you're not in an entity system...
_adminLogs.Add(LogType.MyLog, LogImpact.Medium, $"{entityManager.ToPrettyString(uid)} did something!");

​

Опциональные сущности

​

Компоненты

​

Модификаторы доступа к данным компонента

​

Сеттеры свойств компонентов

​

Ограничения доступа к компонентам

​

Наследование Shared Component

​

Entity Systems

​

Игровая логика

​

Proxy Methods

// Without proxy methods...
EntityManager.GetComponent<MetaDataComponent>(uid).EntityName;

// With proxy methods
Name(uid);

// Without proxy methods...
EntityManager.GetComponent<TransformComponent>(uid).Coordinates;

// With proxy methods
Transform(uid).Coordinates;

​

Сигнатура публичного API метода

public void SetCount(Entity<StackComponent?> stack, int count)
{
    // This call below will set "Comp" to the correct instance if it's null.
    // If all components were resolved to an instance or were non-null, it returns true.
    if(!Resolve(stack, ref stack.Comp))
        return; // If the component wasn't found, this will log an error by default.

    // Logic here!
}

​

Extension Methods

​

Зависимости от других систем

var random = IoCManager.Resolve<IRobustRandom>();
random.Prob(0.1f);

[Dependency] private readonly IRobustRandom _random = default!;
_random.Prob(0.1f);

​

События

​

Method Events vs Entity System Methods

// This would change the damage on the entity by 10.
RaiseLocalEvent(uid, new ChangeDamageEvent(10));

// This would change the damage on the entity by 10.
EntitySystem.Get<DamageableSystem>().ChangeDamage(uid, 10);

​

Именование событий

• Всегда добавляйте суффикс Event к вашим событиям. Пример: DamagedEvent, AnchorAttemptEvent…
• Всегда называйте ваш обработчик событий так: OnXEvent Пример: OnDamagedEvent, OnAnchorAttemptEvent…

​

Struct by-ref events

var ev = new MyEvent();
RaiseLocalEvent(ref ev);

​

C# Events vs EventBus Events

​

Async vs Events

​

UI

​

XAML и UI, определённые в C#

​

Производительность

​

Iterator Methods vs возврат коллекций

​

Sealed Classes

​

События вместо обновлений

​

Захват переменных

void DoSomething(EntityUid otherEntity)
{
    // This is BAD. It will allocate on the heap a lot.
    var predicate = (EntityUid uid)
        => uid == otherEntity;

    // This method doesn't allow us to pass custom data,
    // so we're forced to do a costly variable capture.
    MethodWithPredicate(predicate);
}

void MethodWithPredicate(Func<EntityUid, bool> predicate)
{
    // We do something with the predicate here...
}

void DoSomething(EntityUid otherEntity)
{
    // This is good and much more performant than the example before.
    var predicate = (EntityUid uid, EntityUid otherUid)
        => uid == otherUid;

    // Pass our custom data to this method.
    MethodWithPredicate<EntityUid>(predicate, otherEntity);
}

// This method allows you to pass custom data into the predicate.
void MethodWithPredicate<TState>(Func<EntityUid, TState, bool> predicate, TState state)
{
    // We do something with the predicate here, making sure to pass "state" to it...
}

​

Field Deltas

[RegisterComponent, NetworkedComponent, AutoGenerateComponentState(fieldDeltas: true)]
public sealed partial class MyComponent : Component
{
    [DataField, AutoNetworkedField]
    public bool IsActive;

    [DataField, AutoNetworkedField]
    public int Value;
}

​

Когда использовать field deltas

• Ваш компонент имеет поля, которые меняются с разной скоростью
• Обычно изменяется только подмножество полей
• У вас много сетевых полей, и вы не хотите отправлять их все каждый раз

​

Пометка полей как изменённых

// Instead of this:
comp.IsActive = true;
Dirty(uid, comp);  // Would send ALL networked fields

// Do this:
comp.IsActive = true;
DirtyField(uid, comp, nameof(MyComponent.IsActive));  // Only sends IsActive

​

TimeSpans

​

Использование TimeSpans

​

Обработка приостановленных сущностей

​

AutoGenerateComponentPause и AutoPausedField

• [AutoGenerateComponentPause] применяется к классу компонента и автоматически генерирует код для обработки возобновления.
• [AutoPausedField] применяется к отдельным полям TimeSpan внутри этого компонента, которые должны быть скорректированы при возобновлении сущности.

[RegisterComponent, AutoGenerateComponentPause]
public sealed partial class CooldownComponent : Component
{
    [DataField, AutoPausedField]
    public TimeSpan CooldownEnd;

    [DataField, AutoPausedField]
    public TimeSpan? OptionalTimer;
}

​

TimeOffsetSerializer

• Он автоматически смещает TimeSpan на текущее игровое время во время сериализации/десериализации
• Если сущность приостановлена, используется время, на которое сущность была приостановлена, как точка отсчёта
• Он предотвращает непреднамеренное сохранение временных смещений на картах во время маппинга (prototypes всегда сериализуются как ноль)

[DataField(customTypeSerializer: typeof(TimeOffsetSerializer))]
public TimeSpan NextActivationTime;

​

Именование

​

Shared типы

• Если FooComponent существует только в shared, ему не нужен префикс.
• Если BarComponent существует в shared, server и client, shared тип должен иметь префикс Shared: SharedBarComponent.

​

Физика

​

Anchoring

​

Соглашения по YAML

• Каждый - type компонента должен быть вместе без пустых строк между ними
• Разделяйте prototypes одной пустой строкой.
• Поля name: и description: никогда не должны иметь кавычек, если только пунктуация в имени/описании не требует их использования; в этом случае используйте ”. Например:

  name: 'Spessman's Smokes packet'
  description: 'A label on the packaging reads, 'Wouldn't a slow death make a change?''

• Не указывайте текстуры в абстрактных prototypes/родителях.
• Объявляйте первый блок prototype в таком порядке: type > abstract > parent > id > categories > name > suffix > description > components.
• Используйте инлайн-списки для categories и обычные списки для всего остального:
  - type: entity
    parent: [ PartHuman, BaseHead ] # Inline list
    id: Headhuman
    components:
    - type: Tag
      tags: # Regular list
      - Head
  
• Новые компоненты не должны иметь отступа при добавлении в секцию components:. Так
  components:
  - type: Sprite
    state:
  
  Не так
  components:
    - type: Sprite
      state:
  
• То же правило применяется к любому другому списку или словарю, например:
  - type: Tag
    tags:
    - HighRiskItem # Correct indentation
  
  - type: Tag
    tags:
      - HighRiskItem # Wrong indentation
  
• Когда это имеет смысл, размещайте более общие/движковые компоненты ближе к верху списка компонентов, а более специфичные — ближе к низу. Например,
  components:
  - type: Sprite # Engine-specific
  - type: Physics
  - type: Anchorable # Content, but generalized
  - type: Emitter # A component for a specific type of item
  

​

YAML и именование полей данных

​

Сущности

- type: entity
  abstract: true # remove this line if not abstract
  parent: <nameofparent>
  id:
  name:
  components:
  <rest of file>

​

Суффиксы Entity Prototype

​

Локализация

​

Именование ID локализации

• ID локализации всегда в kebab-case и никогда не должны содержать заглавных букв.
• ID локализации должны быть как можно более специфичными, чтобы избежать пересечения с другими ID. Так
  antag-traitor-user-was-traitor-message = ...
  
  Не так
  traitor-message = ...
  

​

Внутри симуляции или вне симуляции

• Практически всё, касающееся сущностей: взаимодействия, физика, atmos и т.д.
• IC чат
• Состояние раунда (лобби, игра, после игры)

• OOC чат
• Adminhelp
• Голосования админов
• Практически всё, что общается с внешним сервисом, таким как база данных или Discord webhook