Como escrever código legível?
Soluções para a tarefa
Mas o que é um código legível?
Fugindo um pouco do pensamento meramente técnico, um código legível é aquele que, levando em conta a sua complexidade, pode ser compreendido o mais rápido possível. Ele é semântico, traduz a operação de negócio que realiza, buscando — a cada linha — explicitar tudo que está fazendo. Além disso, ele é tecnicamente elegante e organizado. Escrever código legível não é algo fácil ou automático, mas sim uma habilidade que é trabalhada ao longo do tempo.
Existem algumas técnicas que podem ser utilizadas para tornar um código mais limpo, organizado e legível. Abaixo vão algumas dicas básicas:
Utilize nomes que realmente expressem o seu conteúdo. Seja uma variável, uma classe, um método, um parâmetro, um arquivo. Vale a pena pensar bem nos nomes, pois vai economizar tempo no médio e longo prazo. É muito melhor utilizar um nome mais longo porém mais significativo;
Nomes de métodos, especialmente, devem descrever efetivamente seu comportamento. Melhor ainda se puderem estar associados a operações de negócios, por exemplo faturarPedido;
Métodos devem ser o mais curtos possíveis, e devem executar apenas uma tarefa. Aqui, deve-se pensar sempre em refatorar: você pode começar com um método mais procedural, que executa todas as operações necessárias, e depois ir dividindo em diversos métodos menores, cada um com apenas uma ação e com seu nome que deixa muito claro o que ele faz;
Comentários, normalmente, não são uma boa ideia. Se você sentir necessidade de explicar seu código por meiode um comentário, é porque ele está pouco claro. Tente aplicar as demais dicas e deixá-lo mais limpo e legível. Uma ideia interessante é, ao invés de adicionar um comentário, colocar algum tipo de log, explicitando ainda mais a ação, e utilizando dados que tornem esse log significativo ao precisar fazer um troubleshooting;
Procure usar uma padronização para nomes. Por exemplo, qual a diferença entre métodos com os nomes fetchDeliveries, getCustomer e retrievePayment? Todos buscam dados? Se todos eles executam a mesma operação, devem ter o mesmo nome, acompanhados do item que eles trazem, como retrieveOrder, por exemplo, estendendo essa padronização por toda a aplicação.