Guida di stile per il codice Verse

Questa guida fornisce un insieme di standard raccomandati per scrivere codice coerente e facile da aggiornare. Seguendo queste linee guida, gli sviluppatori possono migliorare la leggibilità del codice, ridurre gli errori e facilitare la collaborazione con i membri del loro team. Uno stile di scrittura standardizzato è necessario per garantire che il codice sia facile da comprendere e aggiornare per gli sviluppatori attuali e futuri che lavorano a un progetto.

È altresì importante sottolineare che questa guida propone solamente dei consigli. La scelta finale rimane sempre a discrezione del tuo team.

1. Modelli di denominazione standard

L'assegnazione di nomi appropriati è fondamentale per avere un codice leggibile e facile da aggiornare. Cerca di essere sempre coerente con lo stile di denominazione del tuo codice.

1.1 Da fare

• IsX: spesso utilizzato per nominare variabili logiche al fine di porre una domanda (ad esempio, IsEmpty).

• OnX: una funzione sovraccaricabile chiamata dal framework.

• SubscribeX: sottoscrive l'evento del framework denominato X, spesso passando una funzione OnX.

• MakeC: crea un'istanza della classe c senza sovraccaricare il costruttore c.

• CreateC: crea un'istanza della classe c, avviando il ciclo di vita logico.

• DestroyC: termina il ciclo di vita logico.

• C:c: se stai utilizzando una singola istanza della classe c, è corretto chiamarla C.

1.2 Non farlo

• Sovraccaricare i nomi dei tipi. Chiamali semplicemente thing, non thing_type o thing_class.

• Sovraccaricare i valori di enumerazione. Non utilizzare color := enum{COLOR_Red, COLOR_Green}, ma color := enum{Red, Green}.

2. Nomi

2.1 Tipi con lower_snake_case

I nomi dei tipi devono essere sempre espressi con la struttura lower_snake_case., ovvero in minuscolo con trattini bassi. Ciò vale per tutti i tipi: strutture, classi, definizioni di tipi, tratti/interfacce, enumerazioni ecc.

my_new_type := class

2.2 Interfacce e aggettivi

Le interfacce dovrebbero essere definite con aggettivi, ove possibile, come ad esempio "visualizzabile" o "enumerabile". Quando gli aggettivi non risultano la soluzione più appropriata, puoi aggiungere _interface al sostantivo.

my_new_thing_interface := interface

2.3 PascalCase tutto il resto

Tutti gli altri nomi devono presentare il formato PascalCase. Moduli, variabili membro, parametri, metodi e così via.

MyNewVariable:my_new_type = …

2.4 Tipi parametrici

• Assegna un nome ai tipi parametrici t o thing, dove "thing" spiega cosa deve rappresentare il tipo. Ad esempio: Send(Payload:payload where payload:type) Stai inviando alcuni dati parametrizzati, Payload, di qualsiasi tipo di payload.

• Se esiste più di un tipo parametrico, evita di usare lettere semplici come t, u, g

• Non utilizzare mai il suffisso _t.

3. Formattazione

È importante mantenere una formattazione coerente in tutto il codice. In questo modo sarà più facile per te e per gli altri sviluppatori leggere e comprendere il codice. Scegli uno stile di formattazione adatto al progetto.

Come esempio di coerenza, puoi scegliere uno dei seguenti formati di spaziatura e utilizzarlo in tutto il codice:

MyVariable : int = 5
MyVariable:int = 5

3.1 Indentazione

• Utilizza quattro spazi per ottenere l'indentazione, mai le tabulazioni.

• I blocchi di codice dovrebbero essere costituiti da blocchi indentati (spaziati) piuttosto che da parentesi graffe:

  Verse

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

  Copy full snippet(3 lines long)

  • Tranne per la scrittura di espressioni di una sola riga come Opzione{a}, my_class{A := b}, ecc.

3.2 Spazi

• Inserisci spazi tra un operatore e l'altro, a meno che non sia opportuno mantenere il codice compatto per il suo contesto. Aggiungi parentesi per definire esplicitamente l'ordine delle operazioni.

  Verse

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

  Copy full snippet(1 line long)

• Non aggiungere spazi all'inizio e alla fine delle parentesi. Più espressioni all'interno delle parentesi devono essere separate da un singolo spazio.

  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)

• Mantieni l'identificatore e il tipo insieme; aggiungi uno spazio intorno all'operatore di assegnazione =. Aggiungi uno spazio intorno alle definizioni dei tipi e agli operatori di inizializzazione delle costanti (:=).

  Verse

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

  Copy full snippet(3 lines long)

• Segui le stesse raccomandazioni per le parentesi, gli identificatori e la spaziatura dei tipi per le firme delle funzioni.

  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 Interruzioni di riga

• Utilizza un modulo spaziato e multilinea per inserire un'interruzione di riga.

  Da fare	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)	Più facile da leggere e modificare.
  Non fare	Verse MyTransform := transform{Translation := vector3{Left := 100.0, Up := 200.0, Forward := 300.0}, Rotation := rotation{...}} Copy full snippet(1 line long)	Difficile da leggere su una singola riga.

• Definisci le enumerazioni in un formato spaziato e su più righe, se richiedono commenti specifici per ogni enumerazione o se hai bisogno di inserire un'interruzione di riga.

  Verse

  enum:
      Red, # Desc1
      Blue, # Desc2

  Copy full snippet(3 lines long)

3.4 Parentesi

Non utilizzare parentesi per definizioni di classe non ereditarie.

my_base_type := class:

my_base_type := class():

3.5 Evitare l'uso della notazione a punti e spazi

Evita di utilizzare la notazione a punti ". " al posto delle parentesi graffe. Tale tecnica rende l'analisi della spaziatura visivamente più difficile e può causare confusione.

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

using { Foo } -> using. Foo

4. Funzioni

4.1 Ritorno implicito predefinito

Le funzioni restituiscono il valore dell'ultima espressione. Utilizzala come ritorno implicito.

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

Se si decide di utilizzare i ritorni espliciti, tutti i ritorni della funzione devono essere espliciti.

4.2 Le funzioni GetX devono essere

I getter o le funzioni con una semantica simile che potrebbero non restituire valori validi devono essere contrassegnati con <decides><transacts> e restituire un tipo non opzionale. Il chiamante deve gestire possibili errori.

GetX()<decides><transacts>:x

Un'eccezione riguarda le funzioni che devono scrivere incondizionatamente su una var. Dal momento che un errore potrebbe annullare la mutazione, risulta necessario utilizzare logic o option come tipo di ritorno.

4.3 Preferire metodi di estensione a funzioni a parametro singolo

Utilizza metodi di estensione invece di una funzione con un solo parametro tipizzato.

Questa scelta facilita l'uso di Intellisense. Digitando MyVector.Normalize() invece di Normalize(MyVector), può suggerire nomi con ogni carattere del nome del metodo indicato.

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

Normalize<public>(Vector:vector3):vector3

5. Verifiche di errore

5.1 Limitare a tre il numero di espressioni fallibili su una sola riga

• Limita i controlli condizionali e le espressioni fallibili su una singola riga a un massimo di tre.

  Verse

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

  Copy full snippet(2 lines long)

• Utilizza la forma if con le parentesi () quando il numero di condizioni è inferiore a tre.

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

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

• Se ogni espressione richiede più di due parole, spesso è preferibile avere un massimo di due espressioni su una singola riga per garantire una migliore leggibilità.

  Verse

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

  Copy full snippet(2 lines long)

• Puoi applicare questa regola anche in un contesto di errore su una sola riga, ma senza superare mai nove parole. Quando superi questo limite, utilizza la forma distanziata e su più righe.

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)

• Valuta se raggruppare diverse condizioni fallibili in un'unica funzione <decides> possa rendere il codice più facile da leggere e da riutilizzare. Se il codice viene utilizzato solo in un punto, può essere sufficiente un commento "sezione" senza una funzione ad hoc.

  Verse

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

  Copy full snippet(8 lines long)

• Può essere riscritto come:

  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)

• La stessa linea guida si applica alle espressioni nei loop for. Ad esempio:

  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)

• Meglio come:

  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 Raggruppare le espressioni di errore dipendenti

Quando una condizione in un contesto di errore dipende dall'esito positivo di un precedente contesto di errore, ove possibile, raggruppa le due condizioni nello stesso contesto di errore e segui le linee guida della sezione 5.1.

Questa soluzione migliora la localizzazione del codice, rendendolo più facile da comprendere logicamente e per il debugging.

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)

Puoi anche dividere i contesti di errore, a patto di trattare ogni potenziale errore (o gruppo di errore) separatamente.

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

6.1 Preferire interfacce a classi

Utilizza le interfacce al posto delle classi, ove possibile. Questa scelta consente di ridurre le dipendenze di implementazione e consente agli utenti di fornire implementazioni che possono essere utilizzate dal framework.

6.2 Preferire accesso privato e ambito delimitato

Nella maggior parte dei casi, i membri della classe devono essere "privati".

I metodi delle classi e dei moduli devono essere definiti nel modo più restrittivo possibile (con <internal> o <private>, ove appropriato).

7. Eventi

7.1 Eventi con il suffisso Event e gestori con il prefisso On

I nomi degli eventi sottoscrivibili o degli elenchi di delegati devono avere il suffisso 'Event' mentre i nomi dei gestori di eventi devono avere il prefisso 'On'.

MyDevice.JumpEvent.Subscribe(OnJump)

8. Concorrenza

8.1 Non aggiungere a funzioni l'elemento async

Evita di sovraccaricare le funzioni <suspends> con Async o termini simili.

DoWork()<suspends>:void

DoWorkAsync()<suspends>:void

Puoi aggiungere il prefisso Await a una funzione <suspends> che internamente attende che accada qualcosa. Ciò può aiutare a chiarire come deve essere utilizzata un'API.

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

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

9. Attributi

9.1 Separare gli attributi

Inserisci gli attributi in una riga separata. Questa scelta rende il codice più leggibile, specialmente se più attributi vengono aggiunti a uno stesso identificatore.

@editable
MyField:int = 42

@editable MyField:int = 42

10. Importa espressioni

10.1 Classificare le espressioni di importazione in ordine alfabetico

Ad esempio:

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