Escrevendo boas descrições para suas issues
Quantas vezes você chegou no seu emprego, feliz com a vida, com tudo pronto para ser o dia mais produtivo da sua história?
Você pega aquela issue e começa a codar… Tudo pronto! A felicidade alcança o ápice. Só que a felicidade acaba quando alguém vem e diz pra você que o que você fez não tem nada a ver com o problema a ser solucionado, só que você fez exatamente o que estava escrito na issue.
Daí caímos em duas possíveis premissas: ou você interpretou errado ou a issue está mal descrita.
Dois grandes causadores deste problema são a má interpretação e a má descrição.
Vamos pensar como resolver esses problemas.
Resolvendo o problema de má interpretação de issues
Sim, pessoa, nem sempre o problema é a issue mal descrita. Você pode estar interpretando mal. Seja por pressa em entregar uma feature, porque não quer pensar muito ou qualquer outro motivo que faça com que você não interprete muito bem tudo o que está descrito ali.
Para esse problema a solução é uma só: você deve começar a questionar — a si mesmo e aos outros.
Pergunte para si, antes mesmo de começar a fazer a tarefa:
— Eu realmente entendi o que é pra fazer?
— Não falta nenhuma informação nesta issue?
— Eu tenho tudo o que preciso para desenvolver esta feature?
Você deve buscar começar uma issue sem dúvidas do que fazer, como fazer e qual o resultado a ser buscado.
Se não tiver certeza, pergunte ao restante do time.
Quando você não entende uma issue e já sai escrevendo código ou “resolvendo a issue” você pode acabar criando mais um problema. É mais barato entender e resolver um problema só do que ter dois problemas para resolver.
Como descrever melhor minhas issues
Caso o problema não seja má interpretação, mas realmente uma issue mal descrita, então existem alguns pontos importantes que podemos observar ao escrever uma issue e conseguir um resultado melhor quando alguém pegar isto para resolver.
Uma boa issue deve dizer:
- o que deve ser feito
- quais as áreas/sistemas impactados*
- como deve ser feito*
- qual o resultado buscado
Onde “quais áreas ou sistemas impactados” e “como deve ser feito” são discutidos em alguma reunião estratégica, como a planning, caso você siga alguma metodologia como o Scrum.
Lembrando que o “como” é extremamente subjetivo. Não é escrever um passo a passo de uma solução técnica de o que escrever no código, mas um passo a passo da história do problema.
Não é escrever a lógica para depois transformar em código, porém a regra de negócio deve estar descrita aí.
Um exemplo de issue não muito legal
Recentemente tivemos um caso de issue não muito bem descrita em nosso time. Basicamente era o seguinte:
Título da issue
> Modal de review para produto indisponível
Descrição
> Transpilar o modal de review para os produtos indisponíveis da mesma forma que acontece para produtos disponíveis.
Isso parece uma issue de feature, mas na realidade é uma issue de bug.
O caso real era:
Título da issue
> Não é exibido modal de review para produto indisponível
Descrição
> Quando clicamos em avaliar um produto indisponível o modal não aparece.
> O overlay do modal chega a aparecer, porém sem nenhum conteúdo.
> Como chegar ao problema
> acessar uma categoria e navegar até encontrar um produto indisponível
clicar em “Avaliar produto”
> Possível solução
> Provavelmente o template do produto indisponível `product-unavailable.html` não possui a marcação para exibir o modal.
Alguns detalhes foram ocultados por conta de fazer parte da regra de negócio e especificações do produto, mas você percebe como já houve uma diferença?
Um pouco mais sobre a importância de issues bem descritas:
Frase de uma pessoa que escreveu uma má descrição de issue:
Desculpa cara, eu escrevi a issue pensando em mim e não no time
“Anônimo”
