DEV Community: Luiz Eduardo Cardozo

Padrões de commits - Como e por que?

Luiz Eduardo Cardozo — Sat, 19 Sep 2020 19:08:08 +0000

Se existe algo que programadores gostam (ou, ao menos deveriam gostar mais) são as chamadas “boas práticas”. Elas existem com a finalidade de padronizar o desenvolvimento, criando alguns padrões visuais que exigem menos esforço para se reconhecer do que se trata. Isso além de agilizar o desenvolvimento, também evita erros, aumentando a pouco falada “eficiência”.

Já foram criados padrões para nome de variáveis, nomes de funções, classes… Mas ainda existe um mundo caótico lá fora: as mensagens de commit do git.

Para não perder o costume, vamos a nossa historinha:

Faz alguns poucos meses onde eu e meu time estamos trabalhando em um e-commerce. Estavamos quase ficando sem prazo por conta de alguns imprevistos, então decidimos partir para o stop-the-line para agilizar o processo e isso não acabar se tornando um problema para a nossa fábrica.

Foram 3 dias de trabalho incessante: cerca de 7 programadores trabalhando em cima do mesmo código. Milhões de commits e várias branches abertas, para gerenciar os conflitos.

Por fim, terminamos o projeto bem antes do prazo previsto, com uma sobra de umas duas semanas, que destinamos a testes, antes do deploy final.

Faltando cerca de 3 dias para o lançamento, o Stakeholder do projeto me liga (eram umas 4 da manhã, ele tinha costume de fazer isso) me falando que “as fotos estavam repetidas no site.

Explicando melhor, na página de produto tinha um carrossel. Fazíamos um request à uma api externa, que nos retornava os dados do produto em questão. Por fim, dentro da resposta, possuíam as fotos que o produto deveria apresentar na página inicial. Esses links eram passados para o componente do carrossel.

Bom, o primeiro passo que tive foi lógico: ao final de cada turno, faço um “checklist” de requisitos do sistema, colocando a data. Vi que a última vez que testei o carrossel, foi a cerca de 5 dias antes. Então, fui ao github, e passei a ler todos os commits de cinco dias atrás, caçando algum santo que tenha feito uma modificação no carrossel. Infelizmente, os commits estavam uma bagunça, e eu me vi às 5:30 da manhã, abrindo cada um dos 500 commits feitos, um a um, e lendo os arquivos modificados…

(In)felizmente, não foi culpa nossa… Houve uma falta de sincronia nos serviços da API, e ela acabava fornecendo os dados errados. Coisa que pode ser resolvida com um simples “refresh” no sistema.

Esse fato me fez refletir bastante. Sou um fã assumido de Lean (o modelo de gestão, no caso) e tento aplicar em tudo o que posso. Os commits caóticos me fizeram desperdiçar tempo, e desperdício é o pecado número um do Lean.

Comecei então a bolar métodos de commits que fossem mais claros. Esses métodos têm sido desenvolvidos desde então. Hoje, irei contar um pouco dos meus aprendizados com commits, e como eles facilitam a vida de um tech-leader, ou qualquer desenvolvedor que lide com um equipe grande.

Tudo começa no desenvolvimento

Como você, caro leitor, provavelmente é programador, vamos começar pelo código!

Cada empresa tem a sua particularidade no uso do git: uma branch para cada programador, para cada fase, cada sprint, uma só branch de desenvolvimento, dar push na master...

Como utilizamos o Jira para nos organizar, na empresa onde sou tech-leader, implementei a regra de que cada item do Jira deve possuir uma branch só para ele, nomeada de acordo com o nome sugerido no Jira.

Vamos supor que estamos trabalhando no terceiro item do backlog, cujo o nome é PROJ-003. Então, você deverá dar push todo o seu código relativo a esse item do backlog nessa branch.

Porém, há um adendo: na organização, foco é o primeiro passo.

Faça commit APENAS de itens relativos à branch. Caso ache algum arquivo que precise de modificações, mas não é da alçada daquele item do backlog, não faça commit dessa modificação na branch que está trabalhando atualmente: ou abra uma nova, ou faça na branch correta, depois volte para a sua branch que estava trabalhando.

Isso evita o problema número um que tive com o e-commerce: se algo quebrar em algum ponto, facilmente poderemos rastrear se aquele arquivo foi, ou não, modificado: basta procurar na mensagem de commit.

Como eu devo organizar a minha mensagem?

Bom, existe n formas de se fazer isso. O importante é combinar com a sua equipe um padrão, para que se torne algo “homogêneo” e suficientemente informativo.

Em umas experiências anteriores, nosso chefe nos instruiu a realizar commit apenas após terminar todo o item do backlog. Isso reduz o número de commits, fato, mas aumenta a quantidade de itens commitados, o que é péssimo, já que você vai ter um trabalho bem grande quando for rastrear algum bug.
Em um trabalho posterior, a equipe chegou à conclusão de que o melhor era commitar a cada arquivo modificado, explicando as modificações no arquivo. Isso gera MUITOS problemas:
Quantidade enorme de commits: em caso de bug, só com ctrl + f para achar palavras chaves;
Texto de commit enorme: na hora do desespero, você dificilmente vai conseguir ler tudo;
Prejudica a produtividade: tanto para quem está codando, quanto para quem está tendo que ler os commits, às 5:30 da manhã, com um Stakeholder gritando no telefone;

Agilidade pouco importa no desenvolvimento, se você não tem precisão: Melhor um software bem feito, que uma manutenção rápida.

A maneira mais eficiente que conseguimos chegar de realizar os commits são baseadas em dois eventos:

Quando algo funcional novo foi adicionado;
Quando um bug é corrigido, ou uma funcionalidade foi refatorada

Isso porque: uma funcionalidade, dependendo da arquitetura do sistema, deve interagir com o restante do código. Possivelmente, essa nova funcionalidade pode acabar causando algum “unexpected behavior”. Citar cada funcionalidade nova nos commits, é citar cada ponto de interação do sistema, o que facilita o rastreio do causador do problema.

Já diziam os magos da programação: programar é a arte de gerar bug no código. Eles sempre irão ocorrer, não tem jeito. Eventualmente, a correção de um bug pode gerar um outro bug. Isso se você considerar que o sistema possui testes automatizados, se não, esse “pode gerar um outro bug” se torna um “certamente irá gerar vários outros bugs”, pois é extremamente difícil de manter um padrão de desenvolvimento, se não foi você quem começou ele.

Citar as correções feitas pode facilitar a rastrear algum bug que possa ter ocorrido durante a refatoração de alguma parte do código.

Quanto ao tamanho da mensagem, é relativo: dê preferência por mensagens curtas e objetivas, porém pouco genéricas. Isso ajuda a manter a produtividade durante o processo de escrever código e, é claro, ajuda quem vai ter que rastrear as modificações.

A primeira parte do commit é o motivo dele estar sendo feito. Para eu e minha equipe, temos apenas 5 motivos para isso: adição de algo novo (add), remoção de algo novo velho (remove), correção de um bug (bug-fix) e refatoração de algum código (refact).

Isso ajuda a, no momento que você ver a mensagem de commit, você já ter uma ideia do que houve ali, e se aquilo pode estar ou não integragindo com o seu problema.
A segunda parte é a mais complexa de todas: a mensagem.
A mensagem deve ser curta, no máximo 72 caracteres, e deve ser imperativa. Deve resumir as modificações e especificar o que foi feito e, principalmente, aonde foi feito.

Deve-se também ter cuidado para a mensagem não ficar redundante com a primeira parte. Não existe problemas em se repetir, mas lembre-se dos 72 caracteres. Palavras redundantes são desperdício de tempo e espaço.

Ex:
Mudanças no código - Errado. Vago de mais, que mudanças? Em que parte do código?

Refact: mudanças no código - Errado, porém melhor. Tá, a mudança foi um refatoramento, mas em que parte do código?

Refact: mudanças no componente de produtos - Errado, porém já diz bem mais. Já sabemos que foi um refatoramento, e que foi em um componente de produtos, mas qual foi esse componente?

Refact: mudanças no componente ProductCard - Errado, mas quase bom. Qual forams as mudanças?

Refact: troca do forEach por um map durante o preenchimento dos campos no componente ProductCard - Muito bom! Explica o que foi feito e aonde foi feito. O unico problema é que deveria ser menor…

Refact: forEach trocado por map para preencher campos no componente ProductCard - Perfeito! Pequeno e traz todas as informações necessárias!

Existem algumas ferramentas, como um lint para commits. Eu, particularmente, acho elas um pouco desnecessárias: a maioria te força a usar um idioma e acaba tirando um pouco da sua produtividade. Gosto mais que meu time seja livre, mas tenha conhecimento dos benefícios que seguir um padrão pode trazer.

Esse foi o post hoje e, provavelmente, semana que vem irá sair mais uma parte da minha série de posts sobre testes automatizados. Estou ainda pesquisando materiais para tornar a segunda parte mais densa em conteúdos e, por conta disso, achei melhor postar algo mais “leve” hoje, para não ficarmos sem conteúdo.

Bons estudos a todos!
Luiz Eduardo Cardozo

Jest + TypeScript para quem nunca fez testes - Qual o básico que você precisa saber?

Luiz Eduardo Cardozo — Sat, 12 Sep 2020 17:27:34 +0000

Primeiramente, é interessante você entender qual a real necessidade de se realizar testes automatizados durante o desenvolvimento de alguma aplicação.

Imagina que você está trabalhando em uma API. Você chama uma rota, passando alguns parâmetros para ela, então a rota chama um controlador que, através algumas operações xpto, te retorna uma informação. Pense nela como uma fábrica: você entra com matéria prima (request) e ela te retorna um produto (return).

A entrada da fábrica, seria a rota que chamamos, o interior da máquina, o controlador, seus componentes internos as funções e, por fim, a saída seria o response.

Assim como em uma máquina, para que uma determinada rota funcione bem, todos os seus componentes internos precisam estar funcionando corretamente: isso é, seguindo um padrão de “como funciona”.

Imagine uma linha de produção de carros. Um belo dia, você realiza uma manutenção preventiva em um robô, cujo a função era apertar os parafusos das portas. Porém, sem notar, você acaba invertendo o sentido que a parafusadeira gira… Caos resume a sua linha de produção depois disso. Você irá perder horas de trabalho, tentando entender por que raios os carros estão saindo o parafuso frouxo.

Esse caos poderia ser evitado de uma maneira muito simples:

ao terminar uma manutenção, teste para saber se tudo está funcionando corretamente.

Bom, voltando ao mundo do software, imagine que durante o processo de desenvolvimento, você acaba modificando uma função… Talvez uma modificação simples, que só adicione um parâmetro à saída de uma função. Será que esse parâmetro extra vai quebrar algo no seu código?

Os testes automatizados estão aí justamente para responder essa sua pergunta:com eles é possível checar, de maneira automatizada, todos os inputs e todos os outputs de pedaços do seu código, de forma que seja possível identificar problemas no seu código e corrigi-los rapidamente.

Existem diversas filosofias de desenvolvimento que implementam testes: TDD, BDD, Unit Testing, ATDD… Como esse é apenas um post introdutório, não vou me ater a elas, buscando focar mais em introduzir os novatos nesse mundo de testes.

Passo I - Afiando o machado

Bom, irei partir do princípio de que você já tem todo um ambiente de TypeScript montado e, é claro, saiba ao menos um framework de NodeJS para construirmos algum exemplo. Eu irei utilizar o ExpressJS, por ser simples.

Primeiramente, iremos instalar as ferramentas necessárias para iniciar o trabalho

yarn install --D jest ts-jest @types/jest

Caso esteja de fato utilizando o TypeScript, é de suma importância instalar o ts-jest e os tipos do Jest.

Depois de instalado, deveremos criar um arquivo de configurações para o Jest: jest.config.js

module.exports = {
  roots: ['<rootDir>/src'],
  transform: {
    '^.+\\.tsx?$': 'ts-jest',
  },
  testRegex: '(/__tests__/.*|(\\.|/)(test|spec))\\.tsx?$',
  moduleFileExtensions: ['ts', 'js', 'json'],
}

Importante:
Roots -> Aqui, você deve dizer aonde ficará o código fonte da sua aplicação. Por padrão, eu sempre crio uma pasta src dentro do projeto, para por todo código lá dentro.
testRegex -> Aqui, será o regex que o jest irá utilizar para identificar se um arquivo é, ou não é, um arquivo que contém testes. Isso, porque não dizemos ao jest qual arquivo executar. Por padrão, ele sempre irá executar todos os testes que ele conseguir achar.

Esse é um Regex “padrão”, ele irá buscar por arquivos que contenham o formato:

Nome-do-teste.test.tsx
Nome-do-teste.test.ts
Nome-do-teste.spec.tsx
nome-do-teste.spec.ts

Observe também que ele irá buscar todos esses testes dentro da pasta tests. Caso queira mudar, basta mudar essa sessão do Regex.

Passo II - Criando uma função que será testada

Nossa função de testes será bastante simples, e eu irei implementá-la de uma maneira “não otimizada”, justamente para apresentar um caso de uso dos testes unitários.

A função em questão deverá receber dois arrays, então somar a somatória desses arrays.

Caso você esteja pensando “What the f*ck???” eu vou dar um exemplo prático

sumTest( [1,2,3], [4,5,6] )

sumArray( [ 1, 2, 3 ] ) + sumArray( [ 4, 5, 6 ] )

sumArray( [ 1, 2, 3 ] ) = 1 + 2 + 3 = 6

sumArray( [ 4, 5, 6 ] ) = 4 + 5 + 6 = 15

sumArray( [ 1, 2, 3 ] ) + sumArray( [ 4, 5, 6 ] ) = 6 + 15 = 21

Logo:

sumTest( [1,2,3], [4,5,6] ) = sumArray( [ 1, 2, 3 ] ) + sumArray( [ 4, 5, 6 ] ) = 6 + 15 = 21

Entendido o algorítimo, iremos implementá-lo da seguinte maneira:

função sumTest => recebe a, recebe b :
retorna função sumArray => recebe a + função sumArray => recebe b

Em javascript:

export Const sumArray = (array: Array<Number>): Number {
    Let acumulator = 0;
    Return array.map(number => acumulator + number)
}

export Const sumTest = (a: Array<Number>, b: Array<Number>): Number => {
    Return sumArray(a) + sumArray(b)
}

Salvaremos esse arquivo dentro de:
src/functions/sums.ts

Passo III - Criando os testes

Bom, agora criaremos o nosso arquivo de testes para testar as funçẽs de soma.
Para isso, vamos criar ele da seguinte forma:
src/tests/sums.test.tsx

Inicialmente, devemos importar as funções que vamos testar para o nosso arquivo de testes

import { sumTest, sumArray } from ‘../functions/sums.js’

Agora, usaremos a seguinte sintaxe:

it(“explicação do que a função deve fazer” () => {
    // função sendo executada, e retornando para uma variável
    expect(“<variável”>).toBe(“<valor esperado>”);
});

Vamos supor que você queira testar a seguinte função

const  sum = ( a, b ) => a + b

Sabemos que sum(1,1) deve dar 2, correto?

it(“Deve somar os numeros 1 e 1, retornando 2” () => {
    const resultado = sum(1,1);
    expect(resultado).toBe(2);
});

Caso não seja, essa o jest irá acusar algum erro. Do contrário, irá passar no teste.

Ok, agora vamos voltar ao que interessa, nossas funções de soma.

sumArray => ela soma um array. Logo, sabemos que se passarmos o array [1,2], ela deverá retornar 3, correto?

it(“Deve somar os numeros contidos no array, passados como argumento”, () => {
    Const resultado = sumArray([1,2]);
    expect(resultado).toBe(3);
});

sumTest => ela deve somar os itens contidos nos dois arrays, depois somar os resultados. Se passarmos [1,2] e [1,2] como argumento, ela deverá retornar 6, certo? (1 + 2) + (1 + 2)

it(“Deve somar a somatória dos itens contidos nos dois arrays”, () => {
    Const resultado = sumTest([1,2],[1,2]);
    expect(resultado).toBe(6);
});

Ao executar “jest” na pasta do projeto, ambas as funções irão ser testadas e, se nenhum erro foi cometido, irão passar normalmente. Do contrário, o próprio JEST irá te mostrar aonde função quebrou, mostrando o valor que era esperado, e o valor que foi recebido.

BÔNUS - Refatorando o código sem quebrar nada.

Iremos refatorar a função sumArray de uma maneira simplificada, através da função reduce.

Como ela funciona?

A função reduce é uma função que itera um array, tal qual o map, o forEach, o filter… A diferença é que ela possui um “acumulador”, que soma nele o item atual iterado, aplicado alguma regra (ou sem regras, como é no nosso caso). Terminando a iteração, ela retorna o acumulador.

Podemos reescrever a função da seguinte forma:

const sumArray => (array: Array<Number>): Number => 
array.reduce((i: Number, acumulator: Number) => i + acumulador);

Depois disso, basta rodar novamente o jest e ver que nada quebrou durante os testes.

Esse foi um post curto, apenas para servir de introdução para uma série de posts a respeito de testes que irei fazer. Estudem ele e, em caso de dúvidas, pode entrar em contato comigo!

Bons estudos!