Comentários em Código

[herberthenrique]

Olá,

Recentemente entrei numa discussão com o @wsyssantos sobre comentários em código, onde achamos que 99% dos comentários que encontramos em códigos são desnecessários.
No resumo, concordamos com o seguinte artigo:
http://apdevblog.com/comments-in-code/

Entretanto, trabalhamos com pessoas que dizem que não comentar é não documentar, e que dizeram outros pontos que considero meio absurdos hahaha

E o que vocês acham?

[ghost]

Não foi linus que disse que era bom comentar? rs
eu acho que não precisa comentar cada linha também né?
só algumas palavras chave, deveria ter alguma regra de conduta
sobre isso. :P

[robsonbittencourt]

O livro Clean Code retrata a questão de uma maneira que eu concordo.

Comentários tendem a ser mentirosos. Com o tempo alteramos o código, e não atualizamos os comentários.

"Ahh mas eu sempre atualizo".

Mas e quando você utiliza recursos de refatoração de sua IDE? Como vai fazer para rastrear todos comentários que foram impactados pelo refactory?

No final a única verdade é o código, ele que vai ser executado. Então sempre que sentirmos necessidade de um comentário, deveriamos refletir se o problema não é o nosso código que poderia ser mais simples.

Trazendo para o mundo real, eu utilizo comentários em duas situações. Documentação de APIs quando exigido e código "mágico"/legado que não é possível dar manutenção no momento.

[felquis]

Um amigo me ensinou algo que me chocou, mas nosso próximo código é a documentação.

Claro que, se você usa uma ferramenta que analisa o código e gera uma documentação estática para você, você vai usar comentários nos códigos, pois a documentação é escrita logo ali.

Mas no caso do código do dia-a-dia que não tem uma documentação publica, acaba que a documentação é o próprio código.

// variável usada de prefixo de frases
var y = 'blablabla'

Que tal usar como

var phrasePrefix = 'blablabla'

O mesmo para função, as vezes temos que escolher bons nomes para elas, pois os nomes nos dirão bastante sobre o que ela faz

// export list of users
function export () { /*...*/ }

Que tal algo mais claro

function exportUserList () { /*...*/ }

Muitos comentários sobre detalhes de implementação, contexto, advercidades da vida, todo este texto é importante manter na issue, no PR, no trello card, naquele lugar onde as tarefas são gerenciadas.

Pois se você não estiver de jeito nenhum entendendo aquele código, você pode ver o commit que gerou aquele código, você pode ir até o Pull Request que aquele código foi mergeado na master.

Recomendo assistir este vídeo https://www.youtube.com/watch?v=kw3H7nj9kc4

Então, hoje em dia quando eu sinto necessidade de escrever um comentário eu penso antes

Quais nomes em posso usar nas variáveis e funções para que fique mais claro o que está acontencendo?

Att

[saitodisse]

@robsonbittencourt / @felquis: muito bom, isso mesmo.
Quando precisa de comentários pode ser que o código não está claro o suficiente.

WRITE CODE THAT IS EASY TO READ!
Essa discussão me lembrou deste livro, especialmente este capítulo: http://read.humanjavascript.com/ch03-code-for-humans.html

Mas aí a gente sempre acaba batendo naquele ponto da otimização. Otimização deixa o código ruim de entender. Não tem jeito. Eu, particularmente, prefiro um código 10% / 20% mais lento mas que dê pra fazer manutenção depois.

[rogeriolino]

Os comentários que devem ter no código são os comentários de documentação (/** ... */). E o código em sí deve ser auto-explicativo (como citado acima), o que elimina os comentário sobre o que está acontecendo naquele trecho.

[herberthenrique]

Gostaria primeiramente de dizer que esses comentários me deixam orgulhoso dessa comunidade :D

Eu tenho sério problemas com nomes.
Especialmente se tratando de OOP, exemplo:
Temos a classe Product e dentro dela um método ListProduct, afinal se eu estou dentro do contexto da classe Product pq eu preciso reescrever no nome do método? Mas ai é outra história.

E assim vai.

Ah, assim como @robsonbittencourt comentou do Clean Code.
Leiam esse livro, é incrível!