Somente PaaS

Práticas recomendadas de revisão do código do Adobe Commerce

15 de julho de 2024

Criado para:

  • Experiente
  • Desenvolvedor

O principal objetivo da revisão do código é validar se a funcionalidade implementada atende aos requisitos de maneira ideal das perspectivas de desempenho, arquitetura e segurança.

Além disso, a análise de código tem como objetivo garantir que o código atenda às práticas recomendadas de desenvolvimento da Adobe Commerce, seja fácil de entender e manter e siga os padrões de codificação. A maioria dos padrões de codificação deve ser verificada automaticamente por ferramentas apropriadas.

Processo recomendado de revisão do código

Em um nível superior, o processo de revisão do código deve consistir nas seguintes etapas:

  1. Fazer check-out da ramificação de recursos no ambiente de desenvolvimento local.
  2. Se tiver passado algum tempo desde que o código foi enviado para revisão, mescle as alterações mais recentes da ramificação de destino (geralmente ramificação de controle de qualidade) e envie atualizações para a ramificação de recurso remoto (se houver).
  3. Faça uma revisão de alto nível para validar se o código implementa todos os requisitos. Se houver grandes discrepâncias, entre em contato com o desenvolvedor para obter esclarecimentos.
  4. A execução do código é opcional, mas se você tiver dúvidas de que o código funciona conforme esperado ou se ele facilitar a eficiência do processo, teste se a funcionalidade implementada funciona conforme esperado para os principais cenários de uso. Se houver problemas graves, interrompa o processo de revisão e reabra o ticket com os comentários apropriados.
  5. Faça uma revisão completa para validar se o código implementa todos os requisitos. Se houver problemas, adicione os comentários apropriados à solicitação de pull e reabra o ticket.
  6. Se tudo estiver bem, mescle a solicitação de pull (ou passe-a para o próximo nível de revisão de código, se um tiver sido estabelecido).

Além disso, considere os seguintes pontos ao implementar processos de revisão do código:

  • A revisão do código é uma ferramenta básica para comunicação e transferência de conhecimento em uma equipe. Mesmo que uma solicitação de pull não contenha problemas graves e implemente a lógica de negócios necessária, você pode usá-la como uma oportunidade para sugerir mais melhorias após a mesclagem.

  • Em média, a revisão do código não deve demorar mais de 10% a 20% do esforço de desenvolvimento. Isso pressupondo que a equipe de desenvolvimento seja formada por engenheiros seniores que trabalham bem em conjunto. Se a revisão do código demorar mais, ela pode afetar o orçamento e o cronograma do projeto.

  • Resolva problemas com esforço excessivo necessário para revisões de código identificando a causa raiz. Geralmente, isso ocorre porque os requisitos não são traduzidos adequadamente em tíquetes de desenvolvimento (devido a problemas de comunicação, histórias de usuários ruins) ou porque é um problema de treinamento. No primeiro caso, a mitigação recomendada é garantir que os tíquetes tenham informações suficientes para que os membros da equipe atendam aos requisitos com eficiência. No segundo caso, talvez seja necessário ajustar a estrutura da equipe para incluir engenheiros mais experientes ou obter aprovação fora do mentoreamento e do treinamento.

Produtos e versões afetados

Todas as versõescom suporte de:

  • Adobe Commerce na infraestrutura em nuvem
  • Adobe Commerce no local

O que procurar na revisão do código

Estilo

O estilo pode ser testado automaticamente executando a inspeção PhpStorm (veja abaixo).

Configure o PHPMD e o PHPCS e execute a ferramenta Padrão de Codificação da CLI (também abaixo). Há algumas sobreposições, mas ambas também têm testes únicos.

Convenção e estrutura

As revisões de convenção e estrutura são feitas manualmente.

  • A funcionalidade da classe está limitada a uma única responsabilidade?
  • A estrutura de diretórios faz sentido?
  • É a funcionalidade executada no nível correto (servidor, cliente, CSS, JS, banco de dados, estrutura, infraestrutura).
  • O controle de versão está correto?
  • O código não parece convencional ou está tentando contornar um problema da maneira errada?
  • A convenção de nomenclatura para o nome do módulo, nome do pacote e nome do repositório foi aplicada corretamente?
  • Verifique se os estilos CSS globais foram aplicados cuidadosamente e se não estão sendo usados em excesso.

Integralidade

As análises de integridade são feitas manualmente.

  • O código pode ser ativado ou desativado pela configuração e todo o código necessário se comporta conforme esperado?
  • Há alguma configuração presente que seja mencionada no tíquete? Verifique o escopo, o tipo de dados, a validação, a conversão e os valores padrão.
  • A configuração é sempre recuperada no nível mais baixo possível (nível de exibição de armazenamento, nível de site ou nível global)? A recuperação da configuração deve corresponder à definição do escopo no arquivo system.xml.
  • São abrangidos todos os percursos do fluxograma da especificação técnica? Todas as outras especificações técnicas são abrangidas?
  • As ACLs estão definidas para a nova funcionalidade?
  • O PhpDocs está limpo? As mensagens de confirmação estão limpas?
  • Algum código foi comentado ou você está vendo código de depuração?

Desempenho

As análises de desempenho são feitas manualmente, o que pode ser auxiliado pela execução do código em caso de dúvida.

  • As consultas são executadas em um loop? Este loop pode estar fora dos arquivos editados.
  • Você consegue identificar algum atributo de cachable="false"? Eles são aplicados corretamente?

Segurança

As análises de segurança são feitas manualmente, o que pode ser auxiliado pela pesquisa de texto. Parte da verificação de segurança é tratada por testes automatizados.

  • As exceções são registradas quando necessário? Os tipos corretos de exceções são usados?
  • Os plug-ins around podem ser evitados?
  • Os plug-ins do retornam os tipos corretos de dados?
  • Você pode encontrar consultas SQL brutas que devem ser criadas usando a camada de abstração do banco de dados?
  • Algum novo tipo de dados é exposto a qualquer tipo de usuário, administrador ou front-end? Essa exposição é um risco de segurança?
  • Os dados gerados pelo usuário são validados? Tudo o que vem do navegador é considerado gerado pelo usuário, incluindo valores de cookies e cabeçalhos do servidor.

Privacidade e o RGPD

As revisões de privacidade e de GDPR são feitas manualmente.

  • O código lida com dados ou emails do cliente? Preste atenção especial.
  • Se esse código puder ser executado em um loop, ele poderá vazar dados do cliente de um ciclo de loop para outro?
  • Os indicadores de risco são importações, trabalhos cron, emails transacionais e manipuladores de fila de lotes.
  • Garanta o isolamento dos dados do usuário em loops. Adobe aconselha usar fábricas ou repositórios para criar modelos no ciclo de loop, que não são acessíveis fora do loop.