Melhores práticas para começar um projeto

- 4 minutes read - 691 words

Algumas dicas e guias gerais para começar um projeto.

Defina um repositório git

git init já no começo do projeto ajuda a manter o histórico das mudanças de forma consistente.

Crie o arquivo .gitignore

No arquivo .gitignore, colocamos todos os arquivos temporários do projeto e também resultados de compilação.

Utilize editorconfig

editorconfig é uma forma de padronizar o estilo de código para alguns tipos de arquivos. A maioria dos editores suporta, usando plugins ou nativamente.

Atualize o README.md

Um bom arquivo README serve como documentação de alto nível para os novatos no projeto bem como para os mais experientes. Geralmente uma boa estrutura contém seções sobre: compilação, testes, comandos, design, itens pendentes e questões comuns.

Atualize o CHANGELOG.md

Criar e manter um changelog envolve muita disciplina dos desenvolvedores. Existe recomendações de como criar e manter um em keepachangelog.

Escolha do editor ou IDE

vi, emacs, visual studio code, eclipse, intelliJ IDEA; todos possuem suporte para Elixir e Erlang.

Escolha algum editor ou IDE que tenha um bom suporte e integração com build tool e dialyzer.

Atualmente eu prefiro o visual studio code para Elixir e Erlang.

Build tool

Elixir possui uma ferramenta padrão chamada mix na qual possui todos os comandos que você precisa para criar projetos em Elixir. Além de poder extender a funcionalidade da ferramenta criando novas tasks.

Erlang possui várias abordagens as mais comuns são:

Creio que atualmente a ferramenta mais interessante é o rebar3.

É recomendável gastar um bom tempo estudando os comandos e features da build tool.

Template para código inicial

Elixir

Erlang

Utilize analisadores de boas práticas

Geralmente estas ferramentas oferecem suporte para a definição de regras em um arquivo de configuração e possuem integração com as ferramentas de build.

Elixir

Erlang

Use xref

xref faz checagens de referências a módulos e funções não existentes ou com parâmetros diferentes.

Elixir

Erlang

Use dialyzer

Durante o desenvolvimento, é recomendado enriquecer a documentação de funções, tipos de dados, macros, guards com os famosos type specs (elixir type specs e erlang type specs). Lembrando que tanto Elixir e Erlang são linguagens dinamicamente tipadas.

dialyzer (http://erlang.org/doc/man/dialyzer.html) é uma ferramenta no qual utiliza os type specs para fazer uma análise estática no código e descobrir eventuais problemas.

O esforço de documentar e configurar vale a pena.

Elixir

  • Existem três projetos nos quais adiciona uma nova task ao mix: dialyxir, dialyze, dialyzex
  • O uso do dialyxir parece ser uma boa opção
  • O motivo de haver muitas opções talvez esteja na forma de interpretar os resultados do comando dialyzer.

Erlang

Crie um Makefile para encapsular os comandos repetitivos

  • Caso tenha muitos comandos para realizar determinada ação, é bom criar um Makefile para conter estes comandos repetitivos
  • Geralmente as regras acabam sendo um wrapper para mix ou rebar3

Caso não goste de Makefiles, há opção de compor as tasks e comandos: mix do e rebar3 do

Formate o código com alguma ferramenta automática de formatação

Elixir

  • mix format ajuda a manter o padrão de código. Assim o desenvolvedor não perde tempo arrumando o código

Erlang

  • Não há uma ferramenta padrão. Geralmente é delegado para as IDE e editores. E aí cabe para o desenvolvedor definir um padrão
  • O que mais se aproxima a uma ferramenta padrão é Erlang Mode for Emacs. Existe alguns scripts que chamam Emacs para formatar o código fonte.

Documentação de código

Elixir

  • Utilize o ex_doc no qual vai criar uma documentação html bem eficiente e visualmente elegante.
  • Mas antes, entenda como criar documentação de módulos e funções aqui: Writing Documentation
  • Para gerar documentação: mix docs

Erlang

Execução dos testes

Elixir

  • mix test é a principal interface para execução dos testes
  • excoveralls adiciona algumas tasks extras para criação de relatórios mostrando a cobertura dos testes. Basicamente é um wrapper do mix test --cover

Erlang

  • rebar3 eunit para executação dos testes unitários
  • rebar3 ct para execução dos testes funcionais ou sistêmicos