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

Eu estava navegando em algum código antigo que escrevi (primeiro ano na universidade) e notei que costumava escrever títulos de comentários anteriores a várias partes do código. Coisas como (isso é de um jogo de monopólio):

/*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 indiscutivelmente desnecessário se o código for realmente super claro, mas, enquanto eu vasculhava o arquivo, me surpreendeu o quão forte eu sentia 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 eu me pergunto - você faz isso? Você acha que é uma boa ideia? Ou é demais?

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

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

Eu faço isso o tempo todo. Ambos para marcar o que o código está fazendo e, provavelmente, o mais importante, como você disse, para facilitar a verificação e a localização de um pedaço de código. Às vezes, também, anotarei um processo envolvido nos comentários e 'preencherei' o código sob os comentários à medida que for avançando.

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 é um sinal de que você violou o princípio da 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 esse tipo de princípio de design até o final de um programa de graduação, se é que o fazem. De fato, alguns professores determinam sua violação, a fim de facilitar as notas, colocando tudo em um arquivo. Portanto, sua ignorância de calouros é desculpável, e o fato de que você notou "algo" errado e tentou esclarecer com comentários é até louvável nessas circunstâncias, mas, em geral, é melhor corrigir um design pouco claro do que tentar encobri-lo com comentários.

Eu vejo essas coisas como uma maneira de tornar o código mais claro ou não. Se você pode dizer com base nos métodos no arquivo o que é cada parte, não há necessidade, no entanto, se você precisar ter várias seções, poderá ser útil. Talvez quando um arquivo de código for muito grande, ele precise ser dividido, o que pode reduzir a necessidade de tais comentários.

Eu diria que, se trabalhar dentro de uma equipe para criar um padrão, você estiver pelo menos codificando e comentando da mesma maneira, é mais fácil olhar para o código.

Faço isso porque estou sempre comunicando minha 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 da lógica do que estou fazendo e por quê.

Eu gosto de redundância. Se perco meu caderno de laboratório por um motivo ou outro, ou preciso revisitar o código que escrevi anos atrás, não gosto de ter que juntar o que estava fazendo e por que estava fazendo. Se pelo menos parte dessa lógica estiver no código, ela está documentada o suficiente para eu trabalhar pelo menos novamente.

Eu 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 nos quais eu tenho uma função com nome útil para procurar, eu posso ter várias dezenas de usos bastante semelhantes de algo como uma função geral de modelo linear. É útil poder descobrir qual desses era o "quão sensível 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.

Eu acho que isso é útil em situações em que você tem arquivos de origem gigantescos com dezenas de funções e pode organizá-los livremente em pedaços assim. No entanto, não estou dizendo que gosto mais do que arquivos fonte menores e mais focados ...