“Tem horas em que entender errado é pior do que não entender” Thiago Grulha
Nesse terceiro posts sobre Corda Blockchain falaremos sobre o documentação e README, uma etapa geralmente negligenciada por nós desenvolvedores.
Para que documentar algo que eu já sei?
Sempre que falo sobre documentação de um conhecimento me lembro do seguinte post que escrevi uma vez em que menciono uma história que o já famoso Felipe Belluco uma vez me disse:
Acho interessante que sempre que aprendermos um comando ou algo novo a gente crie uma documentação bem simples.
Isso me trouxe à mente um problema que eu já havia passado com um Gradle há um tempo atrás.
Como todo “bom programador”, criei um projeto para testar umas coisas, porém esqueci de versionar…
Dias depois, passei pelo mesmo problema que tinha resolvido nesse projeto, fui procurar para ver a solução, e tinha deletado o projeto…
Projeto Konami Code
Acho que todo mundo que já trabalhou com desenvolvimento já se deparou uma vez na vida com a situação de interagir com algo que não se faz a ideia de como simular o ambiente localmente ou como testar uma mudança antes de mandar quilo para produção.
Em um dos clientes que trabalhei, uma frase ficou bem marcada em minha mente:
“Você sabe como é, aqui na empresa temos vários projetos, mas cada um tem sua ‘manha’ para executar. Ai ficamos perdendo tempo tentando nos lembrar como fazer isso funcionar projeto a projeto”
Chamo esses projetos de Projetos Konami Code, precisamos de todo uma abstração, sorte, e execuções dos mais diversos comandos para fazer a solução “subir”.
O time cresceu, problema à vista
Outra problemática dessa abordagem é o crescimento do time… Não vamos conseguir passar tão simples os Konami Codes de todos os projetos que ele vai trabalhar, e ai, a gente vira a “própria documentação do código”:
“Como subo o projeto no IntelliJ? Como baixo essa dependência X que não encontro no Maven Repository? Meu projeto não compila, o que eu faço?”
Dentre outras perguntas…
A resposta para esses e outros problemas está na documentação do seu projeto.
Mas documentar o que? Tudo?
Na AIS Digital trabalhamos com ferramentas para documentação de projeto, porém, é bem interessante saber separar o que deveria ser documentado na página do projeto como um todo, e o que deveria ser documentado em cada repositório.
Aqui não vou trazer nenhuma receita de bolo, o ponto que eu sempre sigo é: documentar o máximo que você achar que é necessário, seja na página do projeto, seja no repositório.
Por exemplo: Um repositório que peguei na AIS Digital tinha documentado que para usar o container de um banco em específico era necessário aceitar os termos do mesmo, para podermos baixar a imagem; em outro documentei que em uma abordagem com API First era comum que após a geração de classes o projeto continuasse a apresentar erros porque a IDE ainda não tinha realizado a indexação das novas classes geradas, sendo necessário um refresh para isso.
O ponto aqui é: documente o máximo que tu acha que pode te ajudar a outra pessoa não precisar te mandar email, ligar, mandar Slack para saber como interagir com o projeto!
No caso de projetos no Github, geralmente tento documentar o máximo de coisas, pois não vou ter ferramentas como Confluence, Sharepoint e outras para essa documentação.
Vamos então falar sobre a documentação do nosso repositório no Github.
Conheça os recursos de Markdown de sua solução de versionamento
Diana Regina em um post descreveu com maestria alguns pontos que podem nos ajudar a melhorar a documentação de nosso repositório.
Filipe Dias, uma vez me mostrou esse repositório também, que pode nos ajudar a escrever Awesome READMEs.
Um ponto que os dois tem em comum é chamar a atenção para o suporte a Markdowns da solução de versionamento que se deseja usar…
Por exemplo, no caso do nosso projeto, vocês podem ver que a parte de Instruções nos itens Java 8 e Gradle (Opcional) são itens clicáveis que expandem.
Isso é possível graças a uma tag HTML dentro do README.md
<details><summary><b>Instruções</b></summary>
[Dados a serem ocultados]
</details>
E para os mais críticos que acreditam que Markdown não deve se misturar com HTML, no post Corda Blockchain | Desafio R3 — Pensamentos sobre minha metodologia de aprender algo novo (Parte 3: Sobre Lint) além de falarmos sobre Lint para Kotlin, falaremos sobre um Lint para Markdown.
Voltando a falar sobre tags HTML em Markdown, adivinhem então o que aconteceu quando tentei colocar essas mesmas tags em um projeto que eu estava participando que não estava no GitHub (não me lembro agora se foi no Bitbucket ou GitLab)?
Descobri que existia diferença entre interpretadores de Markdown de acordo com a solução de versionamento:
Em alguns deles você possui, inclusive, tags especiais, como [TOC] (Table of Contents). Essa tag cria um índice do seu projeto, e para tanto, cada cabeçalho irá se tornar um item com uma âncora de acesso “linkada”.
Sendo assim, uma dica é conheça o que você tem em mãos para facilitar sua documentação.
Executando o projeto
Quando pensei em documentar o nosso projeto, pensei em algumas informações e comandos como:
- Obrigatoriedade do Java 8, incluindo um ponto importante para testes (que ainda não fiz o merge por conta da competição que estou participando, e por esse commit ter acontecido depois da data de entrega; esse merge pode ter sido realizado dependendo de quando você esteja vendo esse artigo, procure pela seção Erros ao rodar os testes);
- Não obrigatoriedade de Gradle instalado na máquina para execução do projeto;
- Como clonar o projeto;
- Como gerar os nodes;
- Como rodar os nodes;
- Como executar a “aplicação do banco” e a “aplicação da corretora”
- Dentre outras tasks importantes
Uma vez que o projeto é público, a ideia é tornar mais simples para outras pessoas interagirem com ele e poderem dar feedbacks de melhorias.
Plugins Gradle de documentação
Sobre a parte de documentação, também podemos usar plugins do Gradle. No nosso projeto, os utilizados para documentar estão descritos no arquivo plugins/docs.gradle. Mais sobre como utilizar plugins você pode ver em: Corda Blockchain | Desafio R3 — Pensamentos sobre minha metodologia de aprender algo novo (Parte 1: Sobre Gradle).
O Dokka gera a documentação de cada projeto contido no nosso repositório. Nesse caso, dentro do build de application/cordapp-contracts-states, application/cordapp-flows e application/rest-api é possível ver uma pasta dokka com um HTML de nossas classes. Ainda preciso configuração a agregação de todos os relatórios para o build da raiz.
O Project-Report está mais focado em relatórios de dependências de projeto e tasks de projeto.
O Gradle-Versions é um cara tão fera que resolvi dar para ele um post exclusivo, falaremos sobre ele em Corda Blockchain | Desafio R3 — Pensamentos sobre minha metodologia de aprender algo novo (Parte 4: Sobre Versões Desatualizadas de dependências).
Gitm😜ji e Gitm😜ji-Changelog
Utilizei Gitm😜ji para meus commits serem mais assertivos. A ideia é que uma pessoa pelo emoji tenha ideia do que o commit se propõe a fazer, para não precisar clicar em commit por commit para analisar.
A proposta é ter um commit por ação, para não ficar naqueles commits que alteram tudo no projeto e tu já nem controla mais isso depois. O uso de squash e rebase funcionam de forma linda com esse cara!
Um outro cara bem fera que pretendo usar é Gitm😜ji-Changelog, ele agrega seus commits por tags e facilita a geração de changelog.
No demais é isso… nos encontraremos no próximo post em que falarei sobre como iniciei minha jornada com Kotlin e como um bom Lint é (quase) tudo o que precisamos para aprender uma linguagem nova.
E você tem alguma consideração sobre README ou documentação de repositórios, e quer trocar uma ideia? Só bora…
Esse post faz parte de uma série sobre Corda Blockchain.
A série completa é:
- Corda Blockchain | Desafio R3 — Pensamentos sobre minha metodologia de aprender algo novo (Introdução)
- Corda Blockchain | Desafio R3 — Pensamentos sobre minha metodologia de aprender algo novo (Parte 1: Sobre Gradle)
- Corda Blockchain | Desafio R3 — Pensamentos sobre minha metodologia de aprender algo novo (Parte 2: Sobre Documentação)
- Corda Blockchain | Desafio R3 — Pensamentos sobre minha metodologia de aprender algo novo (Parte 3: Sobre Lint) [não publicado]
- Corda Blockchain | Desafio R3 — Pensamentos sobre minha metodologia de aprender algo novo (Parte 4: Sobre Versões Desatualizadas de dependências) [não publicado]
- Corda Blockchain | Desafio R3 — Pensamentos sobre minha metodologia de aprender algo novo (Parte 5: Sobre Vulnerabilidades de dependências) [não publicado]
- Corda Blockchain | Desafio R3 — Pensamentos sobre minha metodologia de aprender algo novo (Parte 6: Sobre Github flow) [não publicado]
- Corda Blockchain | Desafio R3 — Pensamentos sobre minha metodologia de aprender algo novo (Parte 7: Sobre desenvolvimento em Corda) [não publicado]
- Corda Blockchain | Desafio R3 — Pensamentos sobre minha metodologia de aprender algo novo (Parte 8: Sobre testes em Corda) [não publicado]
- Corda Blockchain | Desafio R3 — Pensamentos sobre minha metodologia de aprender algo novo (Parte 9: Sobre AssertJ) [não publicado]
- Corda Blockchain | Desafio R3 — Pensamentos sobre minha metodologia de aprender algo novo (Parte 10: Sobre testes de arquitetura) [não publicado]
- Corda Blockchain | Desafio R3 — Pensamentos sobre minha metodologia de aprender algo novo (Parte 11: Sobre testes de mutantes) [não publicado]
- Corda Blockchain | Desafio R3 — Pensamentos sobre minha metodologia de aprender algo novo (Parte 12: Sobre JaCoCo) [não publicado]
- Corda Blockchain | Desafio R3 — Pensamentos sobre minha metodologia de aprender algo novo (Parte 13: Sobre SonarQube) [não publicado]
- Corda Blockchain | Desafio R3 — Pensamentos sobre minha metodologia de aprender algo novo (Parte 14: Sobre API First e OpenAPI 3) [não publicado]
- Corda Blockchain | Desafio R3 — Pensamentos sobre minha metodologia de aprender algo novo (Parte 15: Sobre Springboot) [não publicado]
- Corda Blockchain | Desafio R3 — Pensamentos sobre minha metodologia de aprender algo novo (Parte 16: Sobre Mapstruct) [não publicado]
Esse artigo foi escrito ouvindo-se Afterimage | Unveil the Unseen
Original post published at Medium on September 16th, 2020.
Top comments (0)