Guia de estilo de código Verse

Este guia apresenta um conjunto de padrões recomendados para escrever código consistente e de fácil manutenção. Seguindo essas diretrizes, os desenvolvedores podem melhorar a legibilidade do código, reduzir erros e facilitar a colaboração. Um estilo de código padronizado é necessário para garantir que seja fácil de entender e manter pelos desenvolvedores atuais e futuros que trabalham em um projeto.

Este guia apresenta recomendações, mas, em última análise, a escolha é da sua equipe.

1. Padrões de nomenclatura comuns

A nomenclatura é essencial para um código legível e sustentável. Tente ser consistente no estilo de nomenclatura em todo o código.

1.1 O que fazer

• IsX: frequentemente usada para nomear variáveis lógicas para fazer uma pergunta (por exemplo, IsEmpty).

• OnX: uma função sobrecarregável chamada pelo framework.

• SubscribeX: inscrição no evento de framework chamado "X", geralmente passando uma função "OnX" para ele.

• MakeC: crie uma instância da classe C sem sobrecarregar o construtor C.

• CreateC: crie uma instância da classe C, iniciando sua duração lógica.

• DestroyC: encerre a duração da lógica.

• C:c: se estiver trabalhando com uma única instância da classe C, não há problema em chamá-la de C.

1.2 O que não fazer

• Decore nomes de tipos. Basta chamá-la de thing, não thing_type ou thing_class.

• Decore valores de enumeração. Em vez de color := enum{COLOR_Red, COLOR_Green}, use color := enum{Red, Green}.

2. Nomes

2.1 Tipos usam "caixa_baixa"

Nomes de tipos devem ser sempre caixa_baixa. Isso inclui todos os tipos: structs, classes, typedefs, traits/interfaces, enums, etc.

my_new_type := class

2.2 Interfaces são adjetivos

Interfaces devem ser adjetivos sempre que possível, como imprimível, enumerável. Quando adjetivos não parecerem corretos, acrescente _interface ao nome.

my_new_thing_interface := interface

2.3 PascalCase em todo o resto

Todos os outros nomes devem ser usar o formato "PascalCase". Módulos, variáveis de membros, parâmetros, métodos e assim por diante.

MyNewVariable:my_new_type = …

2.4 Tipos paramétricos

• Nomeie tipos paramétricos "t" ou "thing", em que "thing" explica o que o tipo deve representar. Por exemplo: Send(Payload:payload where payload:type) Você está enviando alguns dados parametrizados, Carga útil, de qualquer tipo payload.

• Se houver mais de um tipo paramétrico, evite usar letras únicas, como t, u, g

• Nunca use o sufixo _t.

3. Formatação

É importante manter-se consistente com a formatação em toda a base do código. Assim, o código fica mais fácil de ler e entender para você e outros desenvolvedores. Escolha um estilo de formatação que funcione para o projeto.

Como exemplo de consistência, você pode escolher um dos seguintes formatos de espaçamento e usá-lo em toda a base do código:

MyVariable : int = 5
MyVariable:int = 5

3.1 Recuo

• Use quatro espaços para o recuo, nunca tabulações.

• Os blocos de código devem usar blocos recuados (espaçados) em vez de colchetes (chaves):

  Verse

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

  Copy full snippet(3 lines long)

  • Exceto ao escrever expressões de linha única como option{a}, my_class{A := b}, etc.

3.2 Espaços

• Use espaços ao redor dos operadores, a menos que faça sentido manter o código compacto para o seu contexto. Adicione colchetes para definir explicitamente a ordem das operações.

  Verse

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

  Copy full snippet(1 line long)

• Não adicione espaços nem antes nem depois dos colchetes. Várias expressões dentro de colchetes devem ser separadas por um único espaço.

  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)

• Mantenha o identificador e o tipo juntos; adicione um espaço ao redor do operador = de atribuição. Adicione um espaço ao redor de definições de tipos e operadores de inicialização constante (:=).

  Verse

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

  Copy full snippet(3 lines long)

• Siga as mesmas recomendações para colchetes, identificadores e espaçamento de tipos para assinaturas de função.

  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 Quebras de linha

• Use um formulário espaçado de várias linhas para inserir uma quebra de linha.

  O que fazer	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)	Mais legível e fácil de editar.
  O que não fazer	Verse MyTransform := transform{Translation := vector3{Left := 100.0, Up := 200.0, Forward := 300.0}, Rotation := rotation{...}} Copy full snippet(1 line long)	Difícil de ler em uma única linha.

• Defina enumerações em formato multilinha espaçado se elas precisarem de comentários por enumeração ou se você precisar inserir uma quebra de linha.

  Verse

  enum:
      Red, # Desc1
      Blue, # Desc2

  Copy full snippet(3 lines long)

3.4 Chaves

Não use colchetes para definições de classes não herdadas.

my_base_type := class:

my_base_type := class():

3.5 Evite a notação de ponto-espaço

Evite usar ponto-espaço a notação ". " no lugar de chaves. Ela torna visualmente mais difícil analisar espaços em branco e é uma fonte potencial de confusão.

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

using { Foo } -> using. Foo

4. Funções

4.1 Retorno implícito por padrão

Funções retornam o valor de sua última expressão. Use isso como um retorno implícito.

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

Se estiver usando qualquer retorno explícito, todos os retornos na função deverão ser explícitos.

4.2 As funções GetX devem ser

Getters ou funções com semântica semelhante que podem não retornar valores válidos devem ser marcadas como <decides><transacts> e retornar um tipo sem opção. O chamador deve lidar com possíveis falhas.

GetX()<decides><transacts>:x

Uma exceção são as funções que precisam gravar incondicionalmente em um var. A falha reverteria a mutação, então é necessário usar logic ou option para seu tipo de retorno.

4.3 Prefira métodos de extensão a funções de parâmetros únicos

Use métodos de extensão em vez de uma função com um único parâmetro digitado.

Fazer isso ajuda o IntelliSense. Ao digitar MyVector.Normalize() em vez de Normalize(MyVector), pode-se sugerir nomes com cada personagem do nome do método que você digitar.

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

Normalize<public>(Vector:vector3):vector3

5. Verificações de falha

5.1 Limite a contagem de expressões falíveis de linha única a três

• Limite as verificações condicionais/expressões falíveis em uma única linha a um máximo de três.

  Verse

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

  Copy full snippet(2 lines long)

• Use a forma de if com parênteses () quando o número de condições for menor que três.

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

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

• Se estiver usando mais de duas palavras para cada expressão, um máximo de duas expressões em uma única linha geralmente é mais legível.

  Verse

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

  Copy full snippet(2 lines long)

• Você também pode aplicar a regra como em um contexto de falha em uma única linha. Não use mais de nove palavras. Quando ultrapassar o limite, use o formulário multilinha espaçado.

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)

• Avalie se o agrupamento de várias condições falíveis em uma única função <decides> tornaria o código mais fácil de ler e reutilizar. Observe que, se o código for usado apenas em um local, um comentário e "seção" sem uma função específica pode ser suficiente.

  Verse

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

  Copy full snippet(8 lines long)

• Pode ser reescrito como:

  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)

• A mesma diretriz se aplica a expressões em loops for. Por exemplo:

  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)

• Melhor assim:

  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 Agrupe expressões de falha dependentes

Quando uma condição em um contexto de falha depende do êxito de um contexto de falha anterior, mantenha as duas condições juntas no mesmo contexto de falha quando possível e siga a diretriz 5.1.

Assim, você melhora a localidade do código, o que simplifica a compreensão lógica e a depuração.

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)

É aceitável dividir contextos de falha quando você lida com cada falha potencial (ou grupos de falha) separadamente.

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

6.1 Prefira interfaces a classes

Use interfaces em vez de classes onde for razoável. Isso ajuda a reduzir as dependências de implementação e permite que os usuários forneçam implementações que podem ser usadas pela framework.

6.2 Prefira o acesso privado e restrinja o escopo

Os membros da classe devem ser "private" na maioria dos casos.

Os métodos de classe e módulo devem ter o escopo o mais restritivo possível; <internal> ou <private> quando apropriado.

7. Eventos

7.1 Eventos de pós-fixação com manipuladores de eventos e prefixos com "On"

Eventos assináveis ou nomes de listas de delegados devem ser sufixados com "Event", e nomes de manipuladores de eventos devem ser prefixados com "On".

MyDevice.JumpEvent.Subscribe(OnJump)

8. Simultaneidade

8.1 Não decorar funções com Async

Evite decorar funções <suspends> com Async ou termos semelhantes.

DoWork()<suspends>:void

DoWorkAsync()<suspends>:void

É aceitável adicionar o prefixo Await a uma função <suspends> que espera internamente que algo aconteça. Isso pode esclarecer como uma API deve ser usada.

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

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

9. Atributos

9.1 Separe atributos

Coloque os atributos em uma linha separada. O código fica mais legível, especialmente se vários atributos são adicionados ao mesmo identificador.

@editable
MyField:int = 42

@editable MyField:int = 42

10. Expressões de importação

10.1 Classifique expressões de importação em ordem alfabética

Por exemplo:

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