Por que usar @typespecs em seu código Elixir?

Elixir é uma linguagem dinâmica e concisa, mas nem sempre é fácil garantir a segurança e a legibilidade do código. Felizmente, Elixir oferece uma ferramenta poderosa para ajudar a resolver esses problemas: os @typespecs.

Os @typespecs são anotações de tipo opcionais que podem ser adicionadas a funções e módulos em Elixir. Eles permitem especificar os tipos de argumentos e valores de retorno de uma função, tornando mais fácil garantir que seu código esteja correto e fácil de entender.

Neste artigo, discutiremos o que são os @typespecs, especificações e tipos, suas vantagens, desvantagens, e como eles podem ser usados para tornar o seu código Elixir mais seguro e legível.

O que são @typespecs?

Como dito anteriormente, os @typespecs são anotações de tipo opcionais que podem ser adicionadas a funções e módulos em Elixir e usamos ​​para especificar os tipos de argumentos e valores de retorno de uma função.

Os @typespecs são escritos como comentários acima da função ou módulo que eles descrevem. Por exemplo, a especificação de tipo para uma função que adiciona dois números inteiros seria a seguinte:

@spec add(integer, integer) :: integer
def add(x, y), do: x + y

Aqui, @spec indica que estamos adicionando uma especificação de tipo para a função add. O tipo de argumentos é especificado como integer, integer, e o tipo de retorno é especificado como integer.

Especificações e tipos

Os @typespecs também podem ser usados ​​para especificar tipos de valores de retorno que podem ser nil. Vamos ver alguns exemplos a seguir.

@spec find_user(user_id) :: map | nil
def find_user(user_id), do: ...

Aqui, especificamos que a função find_user recebe um argumento do tipo user_id e retorna um map ou nil.

@type user_id :: integer
@type user :: %{id: user_id, name: String.t(), email: String.t(), age: integer}

@spec find_user(user_id) :: user | nil
def find_user(user_id), do: ...

Nesse exemplo, definimos dois tipos: user_id e user. O user_id é um alias para o tipo integer, que representa o ID de um usuário. O tipo user é um map que contém informações sobre o usuário, como o ID, o nome, o email e a idade.

Na especificação de tipo para a função find_user, usamos o tipo user_id como argumento e especificamos que a função pode retornar um map user ou nil. Isso significa que, se a função encontrar um usuário com o ID fornecido, ela retornará um map user. Caso contrário, ela retornará nil.

@spec get_names() :: [String.t()]
def get_names do
  ["Tomate", "Elixir", "Erlang"]
end

Nesse exemplo, estamos especificando o tipo de retorno de uma função que retorna uma lista de strings.

Da mesma forma, você pode especificar o tipo de retorno de uma função que retorna um map da seguinte forma:

@type user_info :: %{name: String.t(), age: integer}
@spec get_user_info(user_id :: integer) :: user_info
def get_user_info(user_id) do
  %{name: "Floki", age: 4}
end

Os @typespecs também podem ser usados para especificar tipos como listas de maps ou maps de listas. Por exemplo:

@type address :: %{street: String.t(), city: String.t()}
@type person :: %{name: String.t(), age: integer, addresses: [address]}
@spec get_person() :: person
def get_person do
  %{
    name: "Floki",
    age: 4,
    addresses: [
      %{street: "123 Rua A", city: "Rio de Janeiro"},
      %{street: "456 Rua B", city: "Angra dos Reis"}
    ]
  }
end

Podemos também combinar para criar definições de tipos mais complexas. Por exemplo:

@type coordinates :: {integer, integer}
@type circle :: %{center: coordinates, radius: integer}
@type rectangle :: %{top_left: coordinates, bottom_right: coordinates}
@type shape :: circle | rectangle
@spec draw_shape(shape) :: :ok
def draw_shape(shape) do
  # ...
end

Neste exemplo, criamos definições de tipos para coordenadas, círculos e retângulos e, em seguida, combinamos essas definições de tipos para criar um tipo de forma que pode ser um círculo ou um retângulo. A função draw_shape aceita qualquer tipo de forma e retorna :ok.

O mesmo se aplica quando queremos usar os @typespecs para especificar retornos de funções que podem resultar em erros ou mensagens personalizadas:

Retornando erros com @typespecs

@spec get_user(user_id :: integer()) :: {:ok, map()} | {:error, atom()}
def get_user(user_id) do
  case Repo.get(User, user_id) do
    %User{} = user ->
      {:ok, user}
    nil ->
      {:error, :not_found}
  end
end

A função get_user retorna uma tuple com :ok e um map contendo as informações do usuário, ou uma tuple com :error e um átomo representando o tipo de erro ocorrido.

Retornando um Ecto.Changeset com @typespecs:

@spec create_user(user_params :: map()) :: {:ok, User.t()} | {:error, Ecto.Changeset.t()}
def create_user(user_params) do
  changeset = User.changeset(%User{}, user_params)

  case Repo.insert(changeset) do
    {:ok, user} ->
      {:ok, user}
    {:error, changeset} ->
      {:error, changeset}
  end
end

A função create_user retorna uma tuple com :ok e um map contendo as informações do usuário criado com sucesso, ou uma tuple com :error e um Ecto.Changeset contendo informações sobre os erros de validação ocorridos durante a criação do usuário.

Retornando uma mensagem personalizada com @typespecs:

@spec validate_password(password :: String.t(), confirm_password :: String.t()) :: :ok | {:error, String.t()}
def validate_password(password, confirm_password) do
  if password == confirm_password do
    :ok
  else
    {:error, "As senhas não coincidem."}
  end
end

Nesse exemplo, a função validate_password retorna :ok caso as senhas informadas sejam iguais, ou uma tuple com :error e uma mensagem personalizada caso as senhas não coincidam.

Vantagens dos @typespecs

Os @typespecs têm várias vantagens importantes:

• Ajuda a garantir a segurança do seu código: Especificando tipos de argumentos e valores de retorno com @typespecs ajudando a garantir que seu código esteja correto e seguro. Ele também ajuda a detectar erros mais cedo no processo de desenvolvimento, antes que possam se transformar em problemas maiores.

• Torna seu código mais explícito: Especificar tipos de argumentos e valores de retorno com @typespecs torna seu código mais fácil de entender. Isso ajuda a evitar confusão e erros causados por informações ambíguas ou mal documentadas.

• Ajuda na documentação do código: Os @typespecs podem ser usados como parte da documentação do seu código. Isso pode tornar sua API mais fácil de entender e usar para outros desenvolvedores que possam trabalhar em seu projeto.

• Facilita a manutenção do código: Os @typespecs podem ajudar a tornar a manutenção do seu código mais fácil e segura. Quando você altera uma função, pode verificar se a alteração afetou os tipos de argumentos ou valores de retorno da função e atualizar a especificação de tipo em conformidade. Isso ajuda a evitar quebras de código e problemas de integração.

Desvantagens dos @typespecs

Embora os @typespecs tenham muitas vantagens, também existem algumas desvantagens a serem consideradas:

• Podem adicionar complexidade ao código: Especificar tipos de argumentos e valores de retorno pode adicionar complexidade ao código. Isso pode tornar o código mais difícil de entender ou ler para desenvolvedores que não estão familiarizados com os @typespecs.

• Podem aumentar o tempo de desenvolvimento: Especificar tipos de argumentos e valores de retorno pode aumentar o tempo de desenvolvimento. Isso ocorre porque você precisa escrever e atualizar as especificações de tipo à medida que escreve o código.

• Não podem garantir 100% de segurança: Embora os @typespecs possam ajudar a garantir a segurança do seu código, eles não podem garantir 100% de segurança. Você ainda precisa testar e verificar seu código para garantir que ele esteja correto e seguro.

Análise de tipos com Dialyzer

Os @typespecs podem ser usados em conjunto com a ferramenta Dialyzer do Erlang para fornecer uma análise estática de tipos ainda mais poderosa e detectar erros de tipos em tempo de compilação. O Dialyzer é uma ferramenta de análise de tipo estático que pode ser usada para verificar a correção do código Elixir. Ele analisa o código-fonte e os @typespecs em busca de inconsistências e gera avisos e erros se encontrar algum problema.

Para usar o Dialyzer, você precisa instalar o pacote dialyxir e executar o comando mix dialyzer. E então o Dialyzer irá examinar o seu código e fornecer informações detalhadas sobre quaisquer problemas de tipos encontrados.

Conclusão

Os @typespecs são uma ferramenta poderosa e valiosa para o desenvolvimento de código em Elixir. Eles ajudam a garantir a segurança e a legibilidade do código, facilitam a manutenção e a documentação do código e podem ser usados como parte da documentação da API.

Embora os @typespecs possam adicionar complexidade ao código e aumentar o tempo de desenvolvimento, os benefícios superam as desvantagens. Se você está desenvolvendo código em Elixir, é altamente recomendável considerar o uso de @typespecs em suas funções e módulos.

Referências

Elixir Typespecs
Elixir Typespecs and Behaviours
Elixir Typespecs Tutorial
Erlang Type Specifications and Dialyzer

Muito obrigado pela leitura até aqui e espero ter ajudado de alguma forma. Tem alguma sugestão ou encontrou algum problema? por favor deixe-me saber. 💜