Escrevendo documentações

Optamos por escrever nossas documentações em português para facilitar a vida do time e novas pessoas contribuidoras do projeto já que não cobramos que a pessoa saiba inglês no nosso processo de contratação. Além de entendermos ser mais fácil que a pessoa desenvolvedora escreva uma documentação mais rica por ser na lingua materna dela.

Preferimos usar @moduledoc e @doc para documentar módulos e funções, respectivamente. Usamos a lib ex_doc para gerar a documentação estruturada do projeto.

Entretando, nosso código se mantém em inglês para definição de funções, entidades e módulos. Não traduzimos nomenclaturas muito específicas do nosso contexto bancário e solar brasileiro. Com o tempo criaremos um glossário para alguns termos que usamos dentro da aplicação.

Exemplo de código e documentação:

defmodule Xpto.Context do
  @moduledoc """
  Descreva a responsabilidade do módulo.
  """

  @doc """
  Descreva o que a função se propõe a fazer.
  """
  def pay_billet(...) do
    ...
  end
end

Para funções privadas, quando necessário, escrever a documentação através de comentário no código.

# Calcula o valor de Mora da cobrança corrente do cliente
defp calc_mora(...) do
  # Comentário sobre uma implementação específica
  ...
end

• Elixir - Writing Documentation