É possível facilitar a leitura de códigos longos que representam um cálculo?

9

Métodos longos são geralmente considerados ruins, no entanto, no meu código, tenho alguns métodos longos difíceis de entender (mais de 50 linhas). Tenho problemas para facilitar a leitura desses métodos, porque uma única instrução interna já tem mais de 50 linhas e essa instrução única e difícil de ler é criar uma consulta ao banco de dados usando um ORM para executar tarefas específicas nas quais a tarefa executada é claramente indicado no nome do método. O motivo pelo qual a instrução é tão longa porque se une a várias colunas, aplica vários locais e seleciona várias colunas distintas para criar um formato de saída documentado necessário.

Esse código de difícil leitura é considerado ruim? Da mesma forma, se eu escrever código para um algoritmo complicado, resultando em código difícil de ler, envolvido em um método claramente nomeado, esse código é ruim?

readability

— Michael Tsang
fonte

Não existe uma maneira de você parametrizar a consulta de alguma forma? Eu estou supondo que esta consulta varia dependendo do que está acontecendo dentro do método que cria. Talvez você possa dividi-lo em pedaços menores e construí-lo em várias etapas, facilitando a leitura.

— Zalomon

Seu ORM suporta visualizações? Você pode extrair uma (grupo de) junção em uma visualização e depois selecioná-la. Mesmo que a visão não é usada em outros lugares, que pode ajudar a quebrar uma instrução SQL grande

— Caleth

Seu ORM suporta uma linguagem de consulta semelhante a SQL? Se sim, você pode mover a consulta para seu próprio arquivo e ativar o destaque da sintaxe IDE. No seu aplicativo, carregue a consulta do arquivo. Se o seu IDE não suportar exatamente essa linguagem de consulta específica, você poderá se dar bem com a formatação SQL, mesmo que isso não seja perfeito. No entanto, a legibilidade é amplamente aumentada por uma boa formatação. Isso também tem o benefício de que é fácil copiar a consulta para um bloco de notas e fazer modificações lá.

— SpaceTrucker

17

Você escreveu

Esse código de difícil leitura é considerado ruim?

então você definitivamente concorda que é um código difícil de ler e, se é difícil de ler, é difícil manter e evoluir - então acho que você considera o código como sendo "ruim" por suas próprias medidas. No entanto, às vezes não é óbvio como melhorar algo como uma instrução SQL de 50 linhas. As refatorações fáceis do "método de extração" não funcionam e você provavelmente não tem idéia de por onde começar para tornar o código mais legível. Para esses casos, você ainda pode tentar um ou todos os seguintes

mostre o código a alguém com mais experiência do que você na limpeza do código. Se você não tem alguém em sua organização, pode perguntar, tente codereview.stackexchange
tente pesquisar no google pelo problema específico. Para o seu exemplo, coisas como "limpar longa instrução sql" podem ser um bom começo. Você ficará surpreso com a quantidade de artigos encontrados sobre esse tópico e, mesmo que não consiga encontrar uma receita interessante para o seu caso, poderá ter algumas idéias novas
em vez de pedir uma justificativa para as coisas que você não pode fazer, concentre-se nas coisas que você pode fazer para limpar o código pelo menos um pouco, como adicionar quebras de linha apropriadas, indentação adequada, adicionar alguns comentários explicativos, dar a algumas variáveis um melhor nome. Não é improvável que, durante esse processo, forçando-se a reler os detalhes do código, você encontre uma maneira de refatorar o código em unidades menores
prática, prática, prática. "Codificação limpa" não é algo que você aprende em um dia; fica mais fácil com mais experiência. Talvez você não encontre uma solução para o seu problema hoje, mas quando voltar ao código em alguns meses, ele parecerá diferente para você.

— Doc Brown
fonte

Eu discordo um pouco da parte do comentário, se há uma parte complexa do código que é complexa porque não pode ser diferente E não encontrou uma maneira de simplificá-lo, é improvável que os comentários dêem uma visão geral do que está sendo feito. Documentá-lo com algum diagrama seria muito melhor. E um comentário que se refira a essa documentação externa deve ser deixado. É claro que essa situação deve ser excepcional, porque todos sabemos que a manutenção de documentação externa raramente é feita; portanto, quanto menos, melhor. Quanto ao resto, uma boa resposta como sempre.

— 213 Walfrat

@ Walfrat: minha intenção era fornecer uma diretriz geral sobre o processo, não exclusivamente para "50 linhas de código SQL" e não como uma solução "pronta para uso" com todas as abordagens possíveis.

— Doc Brown

Eu sei, eu só queria sugerir que, se algo depois de revisado muitas vezes não puder ser simplificado o suficiente (seja o que for), os comentários provavelmente não ajudarão sobre o que torna essa coisa complexa, pelo que provavelmente será necessária uma documentação externa mínima. No caso específico da consulta ao banco de dados, isso é ainda mais fácil, mostrando um diagrama que mostra como cada parte da consulta se correlaciona.

— 21317 Walfrat

4

Difícil de ler não é ruim - desnecessariamente difícil de ler é ruim.

Algumas coisas são difíceis. Nesse caso, você precisa entender completamente o problema, escrever o código e comentar o melhor possível, para que o próximo desenvolvedor tenha uma chance.

Mas algumas coisas são difíceis apenas porque você as dificultou. Se o problema puder ser simplificado e facilitado, simplifique-o. Se for difícil de entender, mas puder ser razoavelmente dividido em subproblemas, divida-o em subproblemas para simplificá-lo.

— gnasher729
fonte

Exatamente. Tente o seu melhor para tornar o código auto-documentado e use os comentários para preencher as lacunas. (editado: Eu percebi depois de postar meu comentário de que o OP referidas consultas de dados ORM, não SQL.)

— Kyle A

1

ORM para criar um relatório? A sério? Aprenda um pouco de SQL, cara. Linguagens processuais são terríveis nesse tipo de coisa.

SQL é uma linguagem muito melhor projetada para lidar com junções e seleções complicadas. E mesmo se você não conseguir que o SQL fique bonito, existem todos os tipos de ferramentas de visualização disponíveis, nas quais você pode arrastar e soltar objetos de banco de dados em um diagrama e o SQL será gerado para você. Sem mencionar que você poderá ajustar e otimizar a consulta, visualizar seu plano de consulta, fazer com que a plataforma sugira opções adicionais de indexação etc. É apenas muito mais flexível.

Tenho certeza de que algumas pessoas aqui vão discordar de mim, mas o ORM não é adequado para fins de relatórios complicados. Se possível, eu consideraria me afastar disso e avançar para a Linguagem de Consulta Estruturada .

— John Wu
fonte

2

Honestamente, o fato de você não gostar de ORMs é completamente irrelevante para a pergunta.

— Doc Brown

Eu gosto de ORMs muito bem. Estou afirmando que elas não são uma boa ferramenta quando o código "se une a várias colunas, aplica vários locais e seleciona várias colunas distintas para criar um formato de saída documentado necessário", que é o tópico deste segmento.

— John Wu

0

Em geral, código difícil de ler é uma péssima idéia em qualquer lugar - mesmo se você for o único mantenedor - tive várias ocorrências de retorno a alguns anos de código ou mesmo semanas mais tarde e achei difícil entender o que era.

Se você precisar fazer muito em uma única consulta, tente dividi-la entre linhas com comentários incorporados:

query(join(map(condition1, condition2), blah, blah, something(bah, blah, blah)))

Torna-se:

// Why are we doing such an awful single query rather than a sequence of selects?
query( // Description of query
  join( // Why are you doing a join here
    map( // Why a map
      condition1, // What is this
      condition2  // And this
   ), // End Map
   blah, // What, Why?
   blah, // What, Why?
   something( // What does this do?
      bah, // What, Why?
      blah, // What, Why?
      blah // What, Why?
      ) // End Something
   ) // End Join
) // End Query

— Steve Barnes
fonte

Eu sou ambíguo sobre o seu exemplo. os comentários devem explicar por que o código é como é. O que deve ser expressa por os identificadores ...

— Timothy Truckle

@TimothyTruckle Concordo que os identificadores devem identificar claramente o que são, mas geralmente não são claros no código normal - no caso de nomes de campos de registro, geralmente há falta de clareza devido a restrições históricas que encontrei nos casos em que os nomes de campos estavam limitados a 5 caracteres, todos com letras maiúsculas ASCII e não podiam ser alterados devido a requisitos de compatibilidade, por exemplo

— Steve Barnes

0

Além da excelente resposta do @ DocBrown, acho que vale a pena reconhecer que ninguém escreve código "bom" o tempo todo. A codificação está fazendo trocas e, geralmente, é melhor aceitar que você escreveu algo um pouco menos limpo do que gostaria e voltar mais tarde. A refatoração é o processo de melhorar o código ao longo do tempo - e, na minha experiência, é isso que faz uma boa base de código, não "acertar na primeira vez".

E você avalia o código no nível do aplicativo, não no nível dos métodos / linhas de código individuais. Portanto, se você tem um método complexo, mas é claramente nomeado, não acho que você tenha um código "ruim", desde que o método seja coeso.

Nomear é a maior arma que você tem para tornar o código inteligível - dê ao seu método um nome que permita às pessoas que leem seu código pularem o corpo, se necessário. Nomeie suas variáveis etc. de maneira que os leitores possam ver o que representam sem precisar ler as instruções de atribuição.

O próximo passo é garantir que seu método realmente faça apenas uma coisa - os efeitos colaterais dificultam a compreensão do código. Portanto, se seu método retornar dados para um formato de saída, ele também não deve atualizar o status do seu banco de dados para "impresso", ou o que for.

Camadas / componentes é a próxima coisa que você pode fazer - se você tiver vários métodos complexos que geram resultados ORM, agrupe-os para que os leitores do seu código possam assumir que todos se comportam da mesma maneira, sem efeitos colaterais etc.

— Neville Kuyt
fonte