Interessante que a legibilidade aplicada à linguagem natural é medida pela velocidade de leitura e compreensão. Eu acho que uma regra simples pode de fato ser adotada, se um comentário de código em particular não melhorar esta propriedade, ela pode ser evitada .
Por que comentários?
Embora o comentário de código seja uma forma de documentação incorporada, existem várias maneiras nas linguagens de programação de ponta para evitar a programação supérflua "excessivamente documentada" (de código significativo) usando elementos da própria linguagem. Também é uma má idéia transformar código em listagens a partir de um livro de programação, onde instruções individuais são literalmente explicadas de forma quase tautológica (lembre-se do exemplo "/ * incremento i por 1 * /" em respostas já fornecidas), tornando esses comentários relevantes apenas para programadores inexperientes com a linguagem.
Não obstante, é a intenção de tentar comentar o código "sub documentado" (mas sem sentido) que é verdadeiramente "a fonte de todo o mal". A própria existência de código "sub documentado" é um sinal ruim - ou é uma bagunça não estruturada, ou um truque maluco de propósito perdido místico. Obviamente, o valor desse código é questionável, pelo menos. Infelizmente, há sempre exemplos, quando é realmente melhor introduzir um comentário em uma seção de linhas de código formatadas (visualmente agrupadas) do que envolvê-lo em uma nova sub-rotina (pense na "consistência tola" que "é o hobgoblin das mentes pequenas"). .
Legibilidade do código! = comentários de código
O código legível não requer anotações por comentários. Em cada lugar específico do código, há sempre um contexto de uma tarefa que esse código em particular deve alcançar. Se o propósito estiver faltando e / ou o código fizer algo misterioso = evitá-lo a todo custo. Não permita que hacks estranhos preencham seu código - é um resultado direto da combinação de tecnologias de bugs com falta de tempo / interesse para entender as fundações. Evite código místico em seu projeto!
Por outro lado, Programa legível = código + documentação pode conter várias seções legítimas de comentários, por exemplo para facilitar a geração de documentação de "comentários para API".
Siga os padrões de estilo de código
Engraçado o suficiente, a questão não é sobre por que comentar código, é sobre trabalho em equipe - como produzir código em um estilo altamente sincronizado (que todo mundo possa ler / entender). Você está seguindo algum padrão de estilo de código na sua empresa? Seu principal objetivo é evitar escrever código que requeira refatoração, é muito "pessoal" e "subjetivamente" ambíguo. Então eu acho, se alguém vê a necessidade de usar o estilo de código, há uma série de ferramentas para implementá-lo apropriadamente - começando com a educação de pessoas e terminando com a automação para controle de qualidade do código (numerosas dicas, etc) e controle integrado) sistemas de revisão de código.
Torne-se um evangelista de legibilidade de código
Se você concordar que o código é lido com mais frequência do que está escrito. Se a expressão clara de idéias e pensamentos claramente é importante para você, não importa qual idioma é usado para se comunicar (matemática, código de máquina ou inglês antigo). Se sua missão é erradicar a maneira maçante e feia de pensamento alternativo. , o último é de outro "manifesto") .. faça perguntas, inicie discussões, comece a espalhar livros que provocam o pensamento sobre limpeza de código (provavelmente não apenas algo semelhante aos padrões de design de Beck, mas mais como já mencionado by RC Martin ) que abordam a ambigüidade na programação. Além disso, há uma passagem de idéias-chave (citada no livro de O'Reilly sobre legibilidade)
- Simplifique a nomenclatura, o comentário e a formatação com dicas que se aplicam a
cada linha de código
- Refine os loops, a lógica e as variáveis do seu programa para reduzir a complexidade e a confusão
- Ataque problemas no nível da função, como reorganizar blocos de código para executar uma tarefa por vez
- Escreva um código de teste eficaz, minucioso e conciso, além de legível
Cortando "comentando", ainda resta muito (acho que escrever código que não precisa de comentários é um ótimo exercício!). Nomear identificadores semanticamente significativos é um bom começo. Em seguida, estruture seu código agrupando as operações logicamente conectadas em funções e classes. E assim por diante. Um programador melhor é um escritor melhor (claro, assumindo outras habilidades técnicas dadas).