none
Melhores Práticas - Comentários de Código RRS feed

  • 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?

    quarta-feira, 27 de maio de 2015 12:54

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
    quinta-feira, 28 de maio de 2015 10:37

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
    quarta-feira, 27 de maio de 2015 13:25
  • Renato, concordo com você.

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

    quarta-feira, 27 de maio de 2015 13:37
  • 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.

    quarta-feira, 27 de maio de 2015 13:48

  • 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

    quarta-feira, 27 de maio de 2015 15:18
  • 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

    quarta-feira, 27 de maio de 2015 15:26
  • 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!

    quarta-feira, 27 de maio de 2015 17:46
  • 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)

    quarta-feira, 27 de maio de 2015 18:19
  • Renato... plenamente de acordo!

    Natan

    quarta-feira, 27 de maio de 2015 22:05
  • 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
    quinta-feira, 28 de maio de 2015 10:37