Se você não comenta seus códigos, é melhor começar: cada função não comentada que você escreve é uma incomodação a mais que você está criando, gratuitamente, na hora de realizar manutenção no sistema que está desenvolvendo.
Comentários possuem diversos beneficios na manutenção de código, como explicar qual a linha de raciocínio que o programador possuia ao desenvolver uma função, quais os parametros de entrada e saída de uma função, alem de descrever em linguagem humana o que determinada função realiza. Basicamente, comentários funcionam como uma documentação rudimentar para sistemas que não possuem uma documentação redigida.
Imaginem um sistema com dezenas de milhares de linhas de código, e você tendo de realizar manutenção neste. Por onde começar ? Você procura a documentação, mas ela não existe; Você segue seus instintos e encontra os arquivos que iniciam o processo do sistema, e consegue encontrar (com dificuldade ou não) os módulos do sistema que precisa realizar manutenção. Analisando o código, você encontra referencias para dezenas de classes e funções que você não tem a menor idéia de onde se localizam, ou o que estas realizam defact.
É importante não apenas comentar, mas faze-lo direito. Um código mal-comentado é quase tão ruim quanto um não-comentado. A ausência de comentários retira a total esperança de uma fácil compreensão do código, enquanto o mal-comentado dá um pouco de esperança apenas para retira-la mais tarde, porém, ainda assim existem comentários com o qual o programador terá com que se basear na manutenção do código.
Programando orientado a objetos, faço questão de que cada função que desenvolvo tenha pelo menos um cabeçalho com o nome da função e uma descrição simples do que esta faz, quando o nome da função não for o suficiente para descrever a função. Cada bloco de código é comentado, determinando o que estou codificando e aonde estas informações serão utilizadas. Existem funções onde comentários são a maior parte referente à estas, de modo que qualquer pessoa que tiver de realizar manutenção em um módulo onde estas funções são invocadas terá pequena dificuldade em compreender o que a função faz.
Escrever comentários pode parecer uma grande perda de tempo no curto prazo, mas no longo prazo acaba se revelando num grande beneficio para os programadores que tiverem de trabalhar neste sistema.
Imaginava que isto já fazia parte do bom-senso da sub-cultura dos programadores, mas alguns códigos que vi recentemente me provaram o contrario. A seguir: sobre a importância de boa nomenclatura de funções.
0 Responses to “Sem comentários”