ti-enxame.com

Você escreve títulos em comentários de código?

Eu estava navegando em algum código antigo que escrevi (primeiro ano na universidade) e percebi que costumava escrever títulos de comentários precedendo várias partes do código. Coisas como (isto é de um jogo de Banco Imobiliário):

/*Board initialization*/
...code...

/*Player initialization*/
...code...

/*Game logic starts here*/
/*Displaying current situation*/
...code...

/*Executing move*/
...code...

/*Handle special event*/
...code...

/*Commit changes, switch to next player*/
...code...

Isso pode ser redundante e sem dúvida desnecessário se o código for realmente muito claro, mas conforme eu examinava o arquivo, fiquei surpreso com o quão fortemente eu senti que sabia o que estava acontecendo, embora eu mal olhasse para o código real. Definitivamente, posso ver isso como adequado em certas circunstâncias, então me pergunto - você faz isso? Você acha que é uma boa ideia? Ou é demais?

17
EpsilonVector

Este é um cheiro de código. Isso diz o quê e não por que.

Se isso for necessário, divida o código em pequenas funções.

24
Maniero

Eu faço isso o tempo todo. Ambos para marcar o que o código está fazendo e, provavelmente, mais importante, como você disse, para facilitar a varredura e a localização de um trecho de código. Às vezes, também, escrevo um processo envolvido nos comentários e "preencho" o código sob os comentários à medida que prossigo.

13
GrandmasterB

Acho interessante quantas pessoas não gostam da prática sem realmente serem capazes de articular o porquê. A razão pela qual comentários como esse são desaprovados é que eles são um sinal de que você violou o princípio de responsabilidade única . Esse nome específico geralmente é usado apenas em um contexto OO, mas o conceito geral também é chamado de coesão e se aplica a outros paradigmas. As escolas geralmente não ensinam esses tipos de princípios de design até o fim de um programa de graduação, se for o caso. Na verdade, alguns professores determinam sua violação a fim de tornar as coisas mais fáceis de corrigir, amontoando tudo em um arquivo. Portanto, sua ignorância de calouro é desculpável e o fato de você ter notado "algo" errado e tentou esclarecer com comentários é até louvável nas circunstâncias, mas em geral é melhor corrigir um design pouco claro do que tentar encobri-lo com comentários.

6
Karl Bielefeldt

Eu vejo essas coisas como uma forma de tornar o código mais claro ou não. Se você puder dizer com base nos métodos do arquivo o que cada parte é, então não há necessidade, entretanto, se você tem ter várias seções, isso pode ser útil. Talvez quando um arquivo de código se torna muito grande, ele precisa ser dividido, o que pode reduzir a necessidade de tais comentários.

Eu diria que, se trabalhar em equipe para chegar a um padrão, todos vocês estão, pelo menos, codificando e comentando da mesma maneira, então olhar para o código se torna mais fácil.

4
aqwert

Faço isso porque geralmente estou comunicando a intenção a mim mesmo ou, essencialmente, colocando um marcador conveniente para coisas como "A limpeza de dados começa aqui". Normalmente, sob esse título, há um breve resumo sobre a lógica do que estou fazendo e por quê.

Gosto de redundância. Se eu perder meu caderno de laboratório por um motivo ou outro, ou tiver que revisar o código que escrevi anos atrás, não gosto de ter que juntar as peças do que estava fazendo e por que estava fazendo isso. Se pelo menos parte dessa lógica está no código, está documentado o suficiente para que eu pelo menos trabalhe com isso novamente.

Acho que parte da minha inclinação para isso é que uma boa parte da minha programação é de natureza estatística e, portanto, um tanto repetitiva. Embora possa haver alguns trechos de código em que tenho uma função nomeada útil para pesquisar, posso ter várias dezenas de usos bastante semelhantes de algo como uma função de modelo linear geral. É útil ser capaz de descobrir qual deles era o "quão sensíveis são os resultados para o código da Escolha A vs. Escolha B ou C" e qual era outra coisa. Isso geralmente é acelerado por títulos.

3
Fomite

Acho que é útil em situações em que você tem arquivos de origem gigantescos com dezenas de funções e pode organizá-los livremente em blocos como esse. Não estou dizendo que gosto mais disso do que de arquivos de origem menores e mais focados ...

2
µBio