4 Dicas de Boas Práticas de documentação de código
Quem não gosta de abrir um código-fonte e ver ele organizado e legível? Sonho de consumo de todo desenvolvedor, não é mesmo?
Um código bagunçado pode funcionar, mas pode trazer incontáveis problemas e consumir muitas horas de um profissional para entendê-lo na hora de uma manutenção.
“Qualquer um consegue escrever um código que um computador entende.
Bons programadores escrevem códigos que humanos entendem” — Martin Fowler
Roger C. Martin em Clean Code: A Handbook of Agile Software Craftsmanship disse que:
“Aprender a criar códigos limpos é uma tarefa árdua e requer mais do que o simples conhecimento dos princípios e padrões. Você deve suar a camisa, praticar sozinho e ver que cometeu erros, assistir os outros praticarem e errarem, vê-los tropeçar e refazer seus passos, vê-los agonizar para tomar decisões e o preço que pagarão por as terem tomado da maneira errada. ”
Pensando nisso, vamos falar hoje sobre algumas boas práticas que podem ser adotadas para manter um código limpo, fácil de ser desenvolvido e mantido, que poderá melhorar a qualidade e produtividade do time.
Dica 1: Nomes descritivos
Para manter um código legível e de fácil compreensão, é importante que os nomes utilizados em funções, variáveis, métodos e parâmetros estejam relacionados ao que eles fazem. Ou seja, utilize sempre nomes que revelem o propósito de forma clara e objetiva.
- Para métodos, que são utilizados para expressar alguma ação, utilize sempre verbos, como por exemplo: executar, pegar, abrir, cancelar e não use palavras diferentes para o mesmo conceito.
- Classes e objetos devem ter nomes de substantivos.
- Não reuse o mesmo nome de variável na mesma classe em diferentes contextos.
Dica 2: Comente somente o essencial
Normalmente um código com muitos comentários, não é um bom código. Se você precisa escrever um comentário para explicá-lo, está na hora de rever o que você codificou. Muitos comentários podem deixar o código poluído, inelegível e difícil de atualizar.
Seguindo essa premissa, tenha sempre em mente de comentar somente o necessário e revisá-lo quando o código for alterado para não ser esquecido e deixar de retratar a sua funcionalidade.
Dica 3: DRY (Don’t Repeat Yourself)
Esse princípio pode ser traduzido como, não repita a si mesmo, em outras palavras não copie e cole. Não devem existir duas partes no código que desempenhem a mesma função. Quando você copia e cola, você está mais propenso a cometer erros.
Dica 4: Funções pequenas
Funções com várias linhas normalmente são difíceis de serem entendidas e testadas. Outro ponto é que provavelmente ela pode ter mais de uma responsabilidade. Portanto, escreva sempre funções pequenas, que possuem
apenas uma responsabilidade e que possam ser testadas.
Uma regra de ouro é deixar o código sempre melhor do que estava antes.
Criar códigos limpos, legíveis e coesos são a missão de todo desenvolvedor.
Essas são somente 4 boas práticas de programação, mas que possuem uma enorme eficácia no desenvolvimento de software. Se você está buscando melhorar seus padrões de escrita de código, comece por essas que você terá muito menos trabalho.
