Руководство по оформлению кода Verse

В этом руководстве приведён ряд рекомендуемых стандартов написания последовательного кода, который легко поддерживать. Придерживаясь эти рекомендаций, разработчики могут повысить читабельность кода, уменьшить количество ошибок и продуктивней сотрудничать друг с другом. Стандартизованный стиль кода упрощает его понимание и поддержку как текущими, так и будущими разработчиками, работающими над проектом.

В этом руководстве содержатся рекомендации, но в итоге выбор остаётся за вашей командой.

1. Общие шаблоны именования

Именование очень важно для удобочитаемости и сопровождения кода. Старайтесь придерживаться одного стиля именования во всем коде.

1.1 Рекомендации по именованию

• IsX: часто используется для присвоения названий логическим переменным, отвечающим на вопрос (например, isEmpty).

• OnX: переопределяемая функция, вызываемая платформой.

• SubscribeX: подписаться на событие платформы X, при этом для обработки часто используется функция OnX.

• MakeC: создание экземпляра класса <code>c</code> без переопределения конструктора <code>c</code>.

• CreateC: создание экземпляра класса <code>c</code> и начало отсчёта его логического времени существования.

• DestroyC: завершение логического времени существования экземпляра класса <code>c</code>.

• C:c: если вы работаете с одним экземпляром класса <code>c</code>, можно назвать его C.

1.2 Чего не стоить делать

• Перегружать названия типов. Используйте название thing, а не thing_type или thing_class.

• Перегружать значения элементов перечисления. Не color := enum{COLOR_Red, COLOR_Green}, используйте color := enum{Red, Green}.

2. Имена

2.1 Для типов используйте нижний регистр с символами подчёркивания (lower_snake_case)

Все типы следует именовать в нижнем регистре с разделением слов символом подчёркивания: lower_snake_case. Так именуются структуры, классы, определения типов, типажи/интерфейсы, элементы перечислений и т. д.

my_new_type := class

2.2 В названиях интерфейсов следует использовать прилагательные

По возможности используйте прилагательные в именах интерфейсов, к примеру printable (пригодный для печати), перечислимый (enumerable). Если прилагательные использовать нецелесообразно, добавьте к названию _interface.

my_new_thing_interface := interface

2.3 Стиль PascalCase для остальных названий

Для всех прочих имён рекомендуется использовать стиль PascalCase (все слова без пробелов с заглавной буквы, в том числе первое). Для модулей, переменных членов класса, параметров, методов и прочего.

MyNewVariable:my_new_type = …

2.4 Параметрические типы

• Именуйте параметрические типы t или thing, где thing поясняет, что представляет из себя этот тип. Пример: Command(Payload:payload where payload:type) Здесь вы передаёте некоторые параметризованные данные Payload любого типа payload.

• Если существует более одного параметрического типа, избегайте использования одиночных букв, таких как t, u, g

• Никогда не используйте суффикс _t.

3. Форматирование

Форматирование во всей базе кода должно быть унифицированным. Это позволит сделать код более удобочитаемым и понятным как для вас, так и для других разработчиков. Выберите стиль форматирования, который подходит для проекта.

В качестве примера унификации можно выбрать один из следующих форматов использования пробелов во всей базе кода:

MyVariable : int = 5
MyVariable:int = 5

3.1 Отступы

• Используйте четыре пробела для отступа, а не табуляцию.

• В блоках кода следует использовать блоки с отступами (с пробелами), а не фигурные скобки:

  Verse

  my_class := class:
            Foo():void =
                Print("Hello World")

  Copy full snippet(3 lines long)

  • За исключением однострочных выражений, таких как option{a}, my_class{A := b} и т. д.

3.2 Пробелы

• Оставляйте пробелы вокруг операторов, если только не требуется обеспечивать компактность кода в связи с его контекстом. Добавляйте скобки, чтобы однозначно определить порядок операций.

  Verse

  MyNumber := 4 + (2 * (a + b))

  Copy full snippet(1 line long)

• Не ставьте пробелы после открывающих и перед закрывающими скобками. Несколько выражений внутри скобок следует разделять одним пробелом.

  Verse

  MyEnum := enum{Red, Blue, Green}
  MyObject:my_class = my_class{X := 1, Y := 2}
  Vector := vector3{Left := 1000.0, Up := -1000.0, Forward := 0.0}
  Foo(Num:int, Str:[]char)

  Copy full snippet(4 lines long)

• Между идентификатором и типом не должно быть пробелов; пробелы необходимо ставить вокруг оператора присваивания =. Ставьте пробелы вокруг определений типов и операторов инициализации констант (:=).

  Verse

  MyVariable:int = 5
  MyVariable := 5
  my_type := class

  Copy full snippet(3 lines long)

• Следуйте тем же рекомендациям в отношении пробелов вокруг скобок, идентификаторов и типов при определении сигнатур функций.

  Verse

  Foo(X:t where t:subtype(class3)):tuple(t, int) = (X, X.Property)
        Foo(G(:t):void where t:type):void
        Const(X:t, :u where t:type, u:type):t = X

  Copy full snippet(3 lines long)

3.3 Разрывы строк

• Чтобы вставить разрывы строк, записывайте код в нескольких строках с интервалами.

  Делайте так	Verse MyTransform := transform: Translation := vector3: Left := 100.0 Up := 200.0 Forward := 300.0 Rotation := rotation: Pitch := 0.0 Yaw := 0.0 Roll := 0.0 Copy full snippet(10 lines long)	Более удобочитаемый и легче редактировать.
  Так не делайте	Verse MyTransform := transform{Translation := vector3{Left := 100.0, Up := 200.0, Forward := 300.0}, Rotation := rotation{...}} Copy full snippet(1 line long)	Неудобно читать, когда всё в одной строке.

• Записывайте элементы перечисления в нескольких строках с интервалами, если нужно вставить комментарий для каждого из них или разрыв строки.

  Verse

  enum:
      Red, # Desc1
      Blue, # Desc2

  Copy full snippet(3 lines long)

3.4 Скобки

Не используйте скобки в определениях ненаследуемых классов.

my_base_type := class:

my_base_type := class():

3.5 Избегайте обозначений с пробелом после точки

Избегайте использования точки с пробелом «. » вместо скобок. В этом случае сложно оценить число пробелов на глаз, и это может стать причиной ошибок.

spawn { F() } -> spawn. F()

using { Foo } -> using. Foo

4. Функции

4.1 Неявный возврат по умолчанию

Функции возвращают значение последнего выражения. Используйте это как способ неявного возврата.

Sqr(X:int):int =
    X * X # Implicit return

Если используется явный возврат, все возвращаемые значения функции должны быть явными.

4.2 Функции GetX

Методы получения или функции с аналогичной семантикой, которые могут завершаться с ошибкой либо возвращать допустимые значения, должны иметь пометку <decides><transacts> и возвращать тип, не являющийся типом option. За обработку потенциальной ошибки отвечает вызывающая функция.

GetX()<decides><transacts>:x

Исключением являются функции, которым требуется безусловная запись в переменную var. Ошибка приведёт к откату изменений, поэтому их возвращаемое значение должно иметь тип logic или option.

4.3 Используйте методы расширения вместо функций с одним параметром

Используйте методы расширения вместо функций с одним типизированным параметром.

В этом вам поможет система автодополнения ввода. Если набрать MyVector.Normalize() вместо Normalize(MyVector), то при поиске будут предлагаться названия с каждым символом введённого вами названия метода.

(Vector:vector3).Normalize<public>():vector3

Normalize<public>(Vector:vector3):vector3

5. Проверки на ошибки

5.1 Записывайте в одной строке не более трёх выражений с неоднозначным результатом

• Записывайте не более трёх проверок условий/выражений с неоднозначным результатом в одной строке.

  Verse

  if (Damage > 10, Player := FindRandomPlayer[], Player.GetFortCharacter[].IsAlive[]):
            EliminatePlayer(Player)

  Copy full snippet(2 lines long)

• Используйте if со скобками (), когда количество условий меньше трёх.

if (Damage > 10, Player := FindRandomPlayer[]):
    EliminatePlayer(Player)

if:
    Damage > 10
    Player := FindRandomPlayer[]
then:
    EliminatePlayer(Player)

• Если в каждом выражении используется более двух слов, то для сохранения удобочитаемости в одной строке следует записывать максимум два выражения.

  Verse

  if (Player := FindAlivePlayer[GetPlayspace().GetPlayers()], Team := FindEmptyTeam[GetPlayspace().GetTeamCollection().GetTeams()]):
            AddPlayerToTeam(Player, Team)

  Copy full snippet(2 lines long)

• Вы также можете применить это правило при прописывании контекста с возможным отсутствием результата не более девяти слов в одной строке. Если лимит превышен, используйте многострочную форму с интервалами.

if:
    Player := FindAlivePlayer[GetPlayspace().GetPlayers()]
    Team := FindEmptyTeam[GetPlayspace().GetTeamCollection().GetTeams()]
    Character := Player.GetFortCharacter[]
    Character.GetHealth() < 50
then:
    AddPlayerToTeam(Player, Team)
    Character.SetHealth(100)

if (Player := FindAlivePlayer[GetPlayspace().GetPlayers()], Team := FindEmptyTeam[GetPlayspace().GetTeamCollection().GetTeams()], Character := Player.GetFortCharacter[], Character.GetHealth() < 50):
    AddPlayerToTeam(Player, Team)
    Character.SetHealth(100)

• Проверьте, упростит ли группировка нескольких условий с возможным отсутствием результата в одну функцию <decides> чтение кода и его повторное использование. Обратите внимание, что если код используется только в одном месте, будет достаточно добавить комментарий к разделу без создания специальной функции.

  Verse

  if:
            Player := FindRandomPlayer[]
            IsAlive[Player]
            not IsInvulnerable[Player]
            Character := Player.GetFortCharacter[]
            Character.GetHealth < 10
        then:
            EliminatePlayer(Player)

  Copy full snippet(8 lines long)

• Можно переписать так:

  Verse

  GetRandomPlayerToEliminate()<decides><transacts>:player=
            Player := FindRandomPlayer[]
            IsAlive[Player]
            not IsInvulnerable[Player]
            Character := Player.GetFortCharacter[]
            Character.GetHealth < 10
            Player
        if (Player := GetRandomPlayerToEliminate[]):
            Eliminate(Player)

  Copy full snippet(9 lines long)

• То же самое правило применимо к выражениям в циклах for. Пример:

  Verse

  set Lights = for (ActorIndex -> TaggedActor : TaggedActors, LightDevice := customizable_light_device[TaggedActor], ShouldLightBeOn := LightsState[ActorIndex]):
        Logger.Print("Adding Light at index {ActorIndex} with State:{if (ShouldLightBeOn?) then "On" else "Off"}")
        if (ShouldLightBeOn?) then LightDevice.TurnOn() else LightDevice.TurnOff()
        LightDevice

  Copy full snippet(4 lines long)

• Лучше записать код так:

  Verse

  set Lights = for:
           ActorIndex -> TaggedActor : TaggedActors
           LightDevice := customizable_light_device[TaggedActor]
           ShouldLightBeOn := LightsState[ActorIndex]
       do:
           if (ShouldLightBeOn?) then LightDevice.TurnOn() else LightDevice.TurnOff()
           LightDevice

  Copy full snippet(7 lines long)

5.2 Группируйте зависимые выражения c неоднозначным результатом

Если условие в контексте с возможным отсутствием результата зависит от успешного выполнения предыдущего контекста с возможным отсутствием результата, по возможности объедините два условия в одном контексте с возможным отсутствием результата и следуйте рекомендации 5.1.

Это улучшает локальность кода, что упрощает его логическое понимание и отладку.

EliminatingCharacter := EliminationResult.EliminatingCharacter
if (FortCharacter := EliminatingCharacter?, EliminatingAgent := FortCharacter.GetAgent[]):
    GrantNextWeapon(EliminatingAgent)

if:
    FortCharacter := Player.GetFortCharacter[]
    set AgentMap[Player] = 1
    FirstItemGranter:item_granter_device = ItemGranters[0]
then:
    FortCharacter.EliminatedEvent().Subscribe(OnPlayerEliminated)
    FirstItemGranter.GrantItem(Player)

EliminatingCharacter := Result.EliminatingCharacter
if:
    FortCharacter := EliminatingCharacter?
then:
    if:
        EliminatingAgent := FortCharacter.GetAgent[]
    then:
        GrantNextWeapon(EliminatingAgent)

if:
    FortCharacter := Player.GetFortCharacter[]
then:
    FortCharacter.EliminatedEvent().Subscribe(OnPlayerEliminated)
if:
    set AgentMap[Player] = 1
if:
    FirstItemGranter:item_granter_device = ItemGranters[0]
then:
    FirstItemGranter.GrantItem(Player)

Допускается разделять контексты с возможным отсутствием результата, если нужно обрабатывать каждую возможную ситуацию отсутствия результата (или группу таких ситуаций) по отдельности.

if (Player := FindPlayer[]):
    if (Player.IsVulnerable[]?):
        EliminatePlayer(Player)
    else:
        Print("Player is invulnerable, can’t eliminate.")
else:
    Print("Can’t find player. This is a setup error.")

6. Инкапсуляция

6.1 Используйте интерфейсы вместо классов

По возможности используйте интерфейсы вместо классов. Это позволит сократить зависимость от реализации и даст пользователям возможность прописывать реализации, которые могут использоваться инфраструктурой.

6.2 Используйте закрытое (private) обращение и ограничивайте область видимости

В большинстве случаев члены класса должны быть 'закрытыми'.

Область видимости методов класса и модуля должна быть как можно более ограниченной — <internal> или <private>, в зависимости от обстоятельств.

7. События

7.1 События с постфиксом Event и обработчики с префиксом On

Имена событий, на которые можно подписаться, а также списков делегатов должны иметь постфикс `Event`, а имена обработчиков событий должны иметь префикс `On`.

MyDevice.JumpEvent.Subscribe(OnJump)

8. Одновременное выполнение

8.1 Не добавляйте в функции слово Async

Не добавляйте в названия функций <suspends> слово Async или другие подобные слова.

DoWork()<suspends>:void

DoWorkAsync()<suspends>:void

Можно добавить префикс Await в название функции <suspends>, которая в своём теле будет ожидать выполнения какого-либо действия. Это поможет понять, как должен использоваться API.

AwaitGameEnd()<suspends>:void=
    # Setup other things before awaiting game end…
    GameEndEvent.Await()

OnBegin()<suspends>:void =
    race:
        RunGameLoop()
        AwaitGameEnd()

9. Атрибуты

9.1 Разделяйте атрибуты

Записывайте атрибуты в отдельных строках. Это повышает удобочитаемость, особенно если к одному и тому же идентификатору добавлено несколько атрибутов.

@editable
MyField:int = 42

@editable MyField:int = 42

10. Выражения импорта

10.1 Записывайте выражения импорта в алфавитном порядке

Пример:

using { /EpicGames.com/Temporary/Diagnostics }
using { /EpicGames.com/Temporary/SpatialMath }
using { /EpicGames.com/Temporary/UI }
using { /Fortnite.com/UI }
using { /Verse.org/Simulation }