Melhores Práticas - Comentários de Código

Question

Amigos, bom dia.

Esse tópico é mais uma forma de discutirmos sobre as vantagens e/ou desvantagens da utilização de comentários nos códigos nos dias de hoje.

Como toda área, a discussão sobre esse tema tem os seus defensores e os totalmente contra.

Os que defendem consideram como principal vantagem que o próprio código pode vir a se tornar uma documentação da aplicação, e que qualquer pessoa que pegar aquele código consiguirá entende-lo e trabalha-lo sem maiores dificuldades.

Para os que são contra, conseguir identificar dois principais pontos:

• Custa muito caro, ficar documentando código.
• O desenvolvedor acabar desenvolvendo um código pior, porque se preocupa muito com os comentários.
• Dar a manutenção em código já é uma tarefa custosa, imagina adicionar comentários nessa manutenção.
• A única garantia é que a primeira pessoa que escreveu o código o comentou devidamente, não há como garantir a atualização dos comentários.

Na minha opinião, o comentário de código é importante. Porém não mais importante que a escrita de um código que se "auto-comenta", um código bem escrito e planejado passará tranquilamente a ideia do código.

E você? Qual a sua opinião?

Answer 1

Bruno,

Como tudo em nossa área, DEPENDE... kkkkkk

Concordo que um CRUD simples em que vc cadastra dados de um estado ou cidade, se bem implementados, são auto-explicativos.

Agora se vc está desenvolvendo um framework (seja para uso interno na empresa ou, mesmo, disponibilizando no GitHub como um projeto open source), a utilização de comentários de uma forma padronizada possibilitará que gere inclusive uma documentação no mesmo molde daquela que é oferecida pela Microsoft com o .NET.

De qualquer forma, a documentação de código não substitui outras modelagens e artefatos. A prototipação ainda é importantíssima a meu ver, além de documentos detalhando regras de negócio (já que um usuário convencional dependerá da mesma).

Answer 2

Renato, concordo com você.

A documentação "padrão" continuará e sempre será importantissima, porque é a forma como o nosso cliente enxergará o projeto.

Answer 3

Nesse artigo: https://visualstudiomagazine.com/articles/2013/07/26/why-commenting-code-is-still-bad.aspx

O Peter Vogel defende com unhas e dentes a não utilização de comentários nos códigos.

Answer 4

Abrir For Next e comentar "fazer um loop por todos..." ou Coisa coisa = new Coisa() e comentar "instanciar o objeto tal", esse tipo de comentário é o que deve ser revisto.... eu já vi programadores fazerem isso e acharem que é legal.... vai entender!

Ou até mesmo programadores que usam x,y dentro de grandes métodos e se perderem... mas quem é X aqui??????

Sou a favor da regra de negócio ser bem comentada pois ali existem definições que vão além da programação.

---

Natan

Answer 5

Natan, penso o mesmo.

Esse tipo de código "chover no molhado" pra mim é perda de tempo, são coisas muito diretas, num tem o que comentar.

O que eu gosto, e uso muito é o padrão de documentação XML: https://msdn.microsoft.com/en-us/library/vstudio/b2s063f7%28v=vs.100%29.aspx

Utilizando <sumary>, <remarks> e etc.

Porque nesse tipo de comentário, podemos deixar um explicação muito sólida sobre o papel de método, classe, interface e etc, no nosso modelo de negócio.

---

Bruno Abreu

Answer 6

Bacana o tópico. Eu, como to iniciando, achava que comentários eram valiosos. Mas lendo o artigo do Peter Vogel e lendo o que vocês falaram realmente vejo que são casos bem raros que pedem comentários, escrever um framework acho que seria um desses como o Renato falou.

{}s!

Answer 7

Natan,

Compartilho da sua visão.

Só acho válido comentar aspectos técnicos em instruções que não são tão comuns no dia-a-dia ou, mesmo, utilizando recursos com os quais diversos desenvolvedores não estão muito familiarizados (como processamento paralelo e assíncrono)

Answer 8

Renato... plenamente de acordo!

---

Natan

Answer 9

Bom dia Bruno,

Na minha opinião, um comentário construtivo é aquele que explica uma regra de negócio específica. Por exemplo, para o cálculo dos impostos e do preço final de um carro, são feitos alguns cálculos; se a pessoa possui sistemas integrados e em uma tela, é feito uma operação em vários sistemas.

Já um comentário que eu não acho construtivo é na hora de instanciar objetos, passagem do conteúdo da tela para algum objeto na classe, coisas simples, que basta a pessoa ler o código para entender a ação feita.

Esses são exemplos básicos, mas são apenas para demonstrar que o uso de comentários pode ser construtivo ou pode não ter necessidade, dependendo do caso. 

Abs.

Bruno Destro

---

Dicas de programação em .net, C# e SQL - http://smcode.com.br/blog.aspx