Usuário com melhor resposta
Melhores Práticas - Comentários de Código

Pergunta
-
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?
Respostas
-
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
- Marcado como Resposta Marcos SJ quinta-feira, 18 de fevereiro de 2016 15:15
Todas as Respostas
-
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).
- Sugerido como Resposta Pedro Garay terça-feira, 30 de junho de 2015 16:01
-
-
-
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
-
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
-
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!
-
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)
-
-
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
- Marcado como Resposta Marcos SJ quinta-feira, 18 de fevereiro de 2016 15:15