Solucionado (ver solução)
Solucionado
(ver solução)
6
respostas

[Dúvida] Comentários por todo o código

Olá pessoal, tudo bem?

Gostaria de saber a opinião de vocês com relação a comentários no código. Eu particularmente me acostumei a sempre documentar tudo, então acabo gerando muito comentário nos meus códigos: o que cada função faz, qual o objetivo de determinada estrutura, etc... pois sempre penso não só em mim como leitor e analisador do código, mas qualquer pessoa que venha a trabalhar no mesmo, porém muitas vezes me vem a sensação de que estou escrevendo muita coisa sobre o código. Abaixo deixo um exemplo de código que estou estudando e criando, onde peço que se possível deixem uma opinião sobre esse tema relatado, estou voltando ao mundo da programação depois de muitos anos como DevOps / SAP Basis e esse feedback será muito importante. Obrigado

Exemplo de código Daniel Mendes

6 respostas
solução!

Olá! Tudo bem?

Comentar todo o código é muito bom, pois assim você facilita a vida de quem posteriormente pode vê-lo, visto que vai entender com muito mais facilidade e menos esforço do que se estivesse sem toda essa documentação.

Além do mais, imagina que daqui algum tempo você volta para esse mesmo código. Os comentários vão até mesmo lhe ajudar a saber o que você estava fazendo no programa, pois é normal irmos esquecermos a lógica que fizemos depois de muito tempo.

Então, acho uma ótima prática mesmo. Está de parabéns!

Caso este post tenha lhe ajudado, por favor, marcar como solucionado. ✓

Comentar todo o código assim é péssimo! O código deve ser legível por si só, deve ser autoexplicativo, independente de comentários, se você achar necessário comentar uma função talvez seja melhor refatorá-la, definindo bem o nome de cada variável e refazendo talvez a estrutura lógica do fluxo da função. Claro que projetos maiores deve-se documentar o código, mas a documentação normalmente é separada da lógica e do código em si, pois muitos comentários assim acabam atrapalhando a leitura do código. Pense, ao invés de comentar o óbvio, já que sabemos que variáveis armazenam valores, não precisamos escrever que elas armazenam tais valores e sim nomeá-las adequadamente de acordo com o que elas estão armazenando.

É a mesma coisa que escrever um texto em inglês e colocar a tradução ao lado, se você consegue escrever claramente você sabe o que o código está fazendo, e mesmo que você esteja no inicio o ideal é se esforçar a ler o código sem tradução, pois o significado já está no código em si, isto caso você queira de fato se tornar fluente em programação.

Muito Obrigado pela atenção e pelo feedback de vocês, Jhoisnáyra Almeida e Gabriel Sena. Entendo o quanto é importante deixar comentários de auxílio à identificação do código, mas que isso seja claro e objetivo para não poluir com muita informação e deixar redundância de informação.

Att, Daniel Mendes

Pegando as dicas e feedbacks de vocês, refatorei algumas funções, deixei os comentários mais simples e claros e assim vejo que o código ficou muito mais limpo e bem documentado:

Código mais claro e limpo com comentários mais objetivos e funções refatoradas

Bem melhor Daniel, você pode perceber que algumas coisas ficam meio redundantes comentar, por exemplo "Função que movimenta a bolinha na tela", se você bater o olho no código e ler "function movimentaBolinha()", você já sabe que é uma função pois o próprio código está declarado como "function" e se você ler o nome da função "movimentaBolinha", você já sabe o que a função faz, ela movimenta a bola, e já está claro que é na tela do seu computador, afinal aonde mais seria? Você poderia trocar o primeiro comentário ao invés de "criando variáveis da bolinha" para "propriedades da bolinha" ou "definindo propriedades da bolinha". Pode-se notar também que a função "draw" (desenha) na linha 18, não só define a cor de fundo da tela mas também está chamando outras três funções, mostraBolinha(), movimentaBolinha() e verificaColisãoBorda(), sendo assim estas três funções são executadas dentro da função "draw", você pode preferir trocar o comentário de "definindo cor de fundo (quadro)" para "Renderizando elementos", não precisa especificar que é na tela, pois já está claro, e nem precisa especificar quais elementos são pois já sabemos que ela renderiza a bolinha "mostraBolinha()", também cuida da renderização do movimento da bolinha "movimentaBolinha()" e da verificação de colisões "verificaColisãoBorda()".

No início pode não ser tão claro assim, mas o próprio código nos diz o que está fazendo, por isso é tão importante nomear bem as funções e variáveis, caso contrário ficaria bem mais confuso. Por exemplo as variáveis width e height da função verificaColisãoBorda(), são comprimento e altura do quê? Possivelmente das bordas que formam a mesa do game, você poderia trocar o nome dessas variáveis para comprimentoDaMesa e larguraDaMesa. Enfim o legal é isto, pensar em como deixar o código mais claro, sem precisar deixar um comentário, isto ajuda você a exercitar sua lógica e quem for ver o código também conseguirá entender.

Perfeito Gabriel Sena, muito obrigado pela sua análise e explicação.