Przewodnik stylistyczny po kodzie Verse

Ten przewodnik zawiera zbiór zalecanych standardów dotyczących pisania spójnego i łatwego w utrzymaniu kodu. Przestrzegając zawartych w nim wytycznych, twórcy mogą zwiększyć czytelność swojego kodu, ograniczyć ilość błędów i ułatwić współpracę. Znormalizowany styl kodu jest konieczny, aby kod był zrozumiały i łatwy w utrzymaniu dla twórców pracujących przy projekcie zarówno w tej chwili, jak i w przyszłości.

W przewodniku zawarto jedynie zalecenia, jednak to zespół musi zadecydować, czy z nich skorzystać.

1. Wspólne konwencje nazewnictwa

Nazewnictwo ma kluczowe znaczenie dla czytelności kodu i łatwości jego utrzymania. Staraj się stosować jednakowy styl nazewnictwa w całym kodzie.

1.1 Rozwiązania zalecane

• IsX: Często stosowane przy nadawaniu nazw zmiennym logicznym w celu zadania pytania (np. IsEmpty).

• OnX: Funkcja dopuszczająca możliwość przeciążenia wywoływana przez framework.

• SubscribeX: subskrybuje zdarzenie frameworku o nazwie X, często przekazując do niego funkcję OnX.

• MakeC: Utwórz instancję klasy c bez przeciążania konstruktora c.

• CreateC: Utworzenie instancji klasy c poprzez rozpoczęcie jej logicznego czasu życia.

• DestroyC: Zakończenie czasu życia logiki.

• C:c: Jeśli pracujesz z pojedynczą instancją klasy c, możesz nazwać ją C.

1.2 Rozwiązania, których należy unikać

• Upiększanie nazw typów. Nazwij coś po prostu thing, a nie thing_type lub thing_class.

• Udekoruj wartości wyliczeń. Zamiast color := enum{COLOR_Red, COLOR_Green}, użyj color := enum{Red, Green}.

2. Nazwy

2.1 Typy zapisujemy jako ciągi małych liter typu lower_snake_case

Nazwy typów należy zawsze zapisywać w postaci ciągów słów pisanych małymi literami, np. lower_snake_case. Dotyczy to wszystkich typów: struktur, klas, definicji typów, cech/interfejsów, wyliczeń itp.

my_new_type := class

2.2 Interfejsy są przymiotnikami

W miarę możliwości interfejsy powinny mieć postać przymiotników, np. printable czy enumerable oznaczających odpowiednio możliwość drukowania i utworzenia wyliczenia. Jeśli zastosowanie przymiotnika byłoby niewłaściwe, zamiast tego dodaj do nazwy przyrostek _interface.

my_new_thing_interface := interface

2.3 Wszystko inne od wielkiej litery, bez spacji (PascalCase)

Wszystkie inne nazwy powinny być zapisywane od wielkiej litery bez spacji (PascalCase). Moduły, zmienne składowe, parametry, metody itd.

MyNewVariable:my_new_type = …

2.4 Typy parametryczne

• W nazwach typów parametrycznych stosuj t lub thing, gdzie thing objaśnia, co dany typ ma reprezentować. Na przykład: Send(Payload:payload where payload:type) Wysyłasz sparametryzowane dane, Payload, dowolnego typu ładunku.

• * Jeśli występuje więcej niż jeden typ parametryczny, unikaj stosowania pojedynczych liter, takich jak t, u, g

• Nigdy nie używaj przyrostka _t.

3. Formatowanie

Ważne, aby w całej bazie kodu stosować jednakowe formatowanie. Dzięki temu kod będzie bardziej czytelny i zrozumiały dla ciebie oraz innych twórców. Styl formatowania należy dobrać pod kątem konkretnego projektu.

W ramach przykładu zachowania spójności można wybrać jeden z poniższych formatów użycia spacji i stosować go w całej bazie kodu:

MyVariable : int = 5
MyVariable:int = 5

3.1 Wcięcia

• Wcięcia twórz za pomocą czterech spacji, nigdy znaków tabulacji.

• Bloki kodu powinny wykorzystywać bloki z wcięciami (z odstępami) zamiast nawiasów klamrowych:

  Verse

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

  Copy full snippet(3 lines long)

  • Wyjątek stanowią wyrażenia jednowierszowe, takie jak opcja{a}, my_class{A := b} itp.

3.2 Spacje

• Stosuj spacje wokół operatorów, chyba że ze względu na kontekst dobrym pomysłem jest zachowanie zwięzłości kodu. Dodawaj nawiasy, aby w jawny sposób definiować kolejność operacji.

  Verse

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

  Copy full snippet(1 line long)

• Nie dodawaj spacji na początkach ani na końcach wyrażeń w nawiasach. Wiele wyrażeń w nawiasach powinno się rozdzielać pojedynczą spacją.

  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)

• Nie rozdzielaj identyfikatora i typu; dodawaj spację wokół operatora przypisania =. Dodawaj spacje wokół definicji typu i operatorów inicjowania stałych (:=).

  Verse

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

  Copy full snippet(3 lines long)

• Te same zalecenia należy stosować w odniesieniu do nawiasów, identyfikatorów i odstępów między typami w sygnaturach funkcji.

  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 Znaki podziału wiersza

• Stosuj format wielowierszowy, z odstępami, aby wstawić znak podziału wiersza.

  Rozwiązania zalecane	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)	Większa czytelność i łatwiejsza edycja.
  Rozwiązania, których należy unikać	Verse MyTransform := transform{Translation := vector3{Left := 100.0, Up := 200.0, Forward := 300.0}, Rotation := rotation{...}} Copy full snippet(1 line long)	Czytanie kodu jednowierszowego jest trudne.

• Definiuj wyliczenia w formie wielowierszowej, z odstępami, jeśli wymagają one wstawienia komentarzy do poszczególnych pozycji lub jeśli musisz wstawić znak podziału wiersza.

  Verse

  enum:
      Red, # Desc1
      Blue, # Desc2

  Copy full snippet(3 lines long)

3.4 Nawiasy

Nie stosuj nawiasów w definicjach klas niedziedziczących.

my_base_type := class:

my_base_type := class():

3.5 Unikanie notacji kropka-spacja

Unikaj używania notacji kropka-spacja ". " zamiast nawiasów. To utrudnia wizualnie analizowanie spacji i może stanowić potencjalne źródło nieporozumień.

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

using { Foo } -> using. Foo

4. Funkcje

4.1 Wywnioskowany zwracany wynik jako domyślny

Funkcje zwracają wartość ich ostatniego wyrażenia. Wykorzystaj ją jako wywnioskowany zwracany wynik.

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

W przypadku użycia dowolnych jawnych wartości zwracanych, wszystkie zwracane wartości w funkcji powinny być jawne.

4.2 Funkcje GetX powinny być następujące:

Gettery lub funkcje o podobnej semantyce, które mogą nie zwrócić prawidłowych wartości, powinny być oznaczone jako <decides><transacts> i zwracać typ niebędący opcją. Wywoływacz powinien obsługiwać potencjalne niepowodzenie.

GetX()<decides><transacts>:x

Wyjątek stanowią funkcje, które wymagają bezwarunkowego zapisu w var. Niepowodzenie spowoduje wycofanie mutacji, więc muszą użyć logic lub option dla swojego typu zwracanego.

4.3 Metody rozszerzające lepsze od funkcji pojedynczych parametrów

Zamiast funkcji z parametrem jednego typu lepiej stosować metody rozszerzające.

Taki sposób postępowania ułatwia korzystanie z funkcji IntelliSense. Wpisanie MyVector.Normalize() zamiast Normalize(MyVector) pozwala funkcji podpowiadać nazwy z każdym wpisywanym znakiem nazwy metody.

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

Normalize<public>(Vector:vector3):vector3

5. Sprawdzanie niepowodzeń

5.1 Ograniczenie liczby wyrażeń zawodnych w jednym wierszu do trzech

• Ograniczaj liczbę kontroli warunkowych / wyrażeń zawodnych w jednym wierszu do maksymalnie trzech.

  Verse

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

  Copy full snippet(2 lines long)

• Stosuj wyrażenie if w postaci z nawiasami (), gdy liczba warunków jest mniejsza niż trzy warunki.

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

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

• W przypadku użycia więcej niż dwóch słów dla każdego wyrażenia, często bardziej czytelne będzie zastosowanie maksymalnie dwóch wyrażeń w jednym wierszu.

  Verse

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

  Copy full snippet(2 lines long)

• Można również zastosować taką zasadę, jak w pojedynczym wierszu kontekstu niepowodzenia, aby nie używać więcej niż dziewięciu słów. Po przekroczeniu limitu stosuj zapisy wielowierszowe z odstępami.

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)

• Oceń, czy zgrupowanie wielu warunków zawodnych do pojedynczej funkcji <decides> zwiększy czytelność kodu i ułatwi jego ponowne wykorzystanie. Zwróć uwagę, że jeśli kod jest używany wyłącznie w jednym miejscu, komentarz "section" bez funkcji ad hoc może wystarczyć.

  Verse

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

  Copy full snippet(8 lines long)

• Można zapisać jako:

  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)

• Te same wytyczne obowiązują w przypadku wyrażeń w pętlach for. Na przykład:

  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)

• Lepiej jako:

  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 Grupowanie ze sobą zależnych wyrażeń zawodnych

Gdy warunek w kontekście niepowodzenia zależy od powodzenia poprzedniego kontekstu niepowodzenia, w miarę możliwości połącz ze sobą dwa warunki w jednym kontekście niepowodzenia, korzystając przy tym z wytycznych w punkcie 5.1.

Poprawi to lokalność kodu, co ułatwi zrozumienie jego logiki oraz debugowanie.

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)

Dzielenie kontekstów niepowodzenia jest dopuszczalne, jeśli zajmujesz się każdym potencjalnym niepowodzeniem (lub grupami niepowodzeń) oddzielnie.

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

6.1 Preferowanie interfejsów zamiast klas

W uzasadnionych przypadkach stosuj interfejsy zamiast klas. Pomaga to ograniczyć zależności implementacji i umożliwia użytkownikom wprowadzanie implementacji, które mogą być wykorzystane przez framework.

6.2 Preferowanie dostępu prywatnego i ograniczania zakresu

W większości przypadków elementy członkowskie klas powinny być oznaczone jako 'private'.

Zakres metod modułów i klas powinien być ograniczony w możliwie jak najbardziej restrykcyjny sposób, w miarę możliwości za pomocą identyfikatorów <internal> lub <private>.

7. Zdarzenia

7.1 Przyrostek Event w zdarzeniach i przedrostek On w handlerach

Zdarzenia, które można subskrybować, lub nazwy list delegatów powinny mieć przyrostek 'Event', a nazwy handlerów zdarzeń powinno się poprzedzać przedrostkiem 'On'.

MyDevice.JumpEvent.Subscribe(OnJump)

8. Współbieżność

8.1 Unikanie dekorowania funkcji dopiskiem Async

Unikaj dekorowania funkcji <suspends> dopiskiem Async lub podobnymi hasłami.

DoWork()<suspends>:void

DoWorkAsync()<suspends>:void

Dopuszczalne jest dodawanie przedrostka Await do funkcji <suspends>, która wewnętrznie oczekuje na jakieś zdarzenie. To może określić sposób, w jaki interfejs API ma być używany.

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

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

9. Atrybuty

9.1 Oddzielanie atrybutów

Dodawaj atrybuty w oddzielnych wierszach. Dzięki temu kod jest bardziej czytelny, zwłaszcza jeśli doda się wiele atrybutów do tego samego identyfikatora.

@editable
MyField:int = 42

@editable MyField:int = 42

10. Importowanie wyrażeń

10.1 Alfabetyczne sortowanie wyrażeń importu

Na przykład:

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