¿Escribes títulos en los comentarios de código? [cerrado]

Estaba navegando por un código antiguo que escribí (primer año en la universidad) y noté que solía escribir títulos de comentarios que precedían a varias partes del código. Cosas como (esto es de un juego de Monopoly):

/*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...

Esto podría ser redundante y posiblemente innecesario si el código es realmente súper claro, pero cuando escaneé el archivo me sorprendió lo mucho que sentí que sabía lo que estaba sucediendo a pesar de que apenas miré el código real. Definitivamente puedo ver esto como apropiado en ciertas circunstancias, así que me pregunto: ¿haces esto? ¿Crees que es una buena idea? ¿O es demasiado?

Este es un código de olor. Esto dice qué y no por qué .

Si esto es necesario, divida el código en pequeñas funciones.

Lo hago todo el tiempo. Ambos para marcar lo que está haciendo el código, y probablemente lo más importante, como dijiste, para que sea más fácil escanear y encontrar un fragmento de código. A veces, también, escribiré un proceso involucrado en los comentarios y 'completaré' el código debajo de los comentarios a medida que avance.

Encuentro interesante cuántas personas no les gusta la práctica sin realmente poder articular por qué. La razón por la cual los comentarios como ese están mal vistos es porque son una señal de que has violado el principio de responsabilidad única. Ese nombre específico generalmente solo se usa en un contexto OO, pero el concepto general también se llama cohesión y se aplica a otros paradigmas. Las escuelas no suelen enseñar ese tipo de principios de diseño hasta el final de un programa de grado, si es que lo hacen. De hecho, algunos maestros ordenan su violación para facilitar la calificación al agrupar todo en un archivo. Por lo tanto, su ignorancia de primer año es excusable, y el hecho de que haya notado que "algo" está mal y haya tratado de aclararlo con comentarios es incluso loable bajo las circunstancias, pero en general es mejor arreglar un diseño poco claro en lugar de tratar de ocultarlo con comentarios.

Miro estas cosas como una forma de aclarar o no el código. Si puede determinar en función de los métodos en el archivo qué es cada parte, entonces no hay necesidad, sin embargo, si tiene que tener varias secciones, puede ser útil. Quizás cuando un archivo de código se hace demasiado grande necesita ser desglosado, lo que podría reducir la necesidad de tales comentarios.

Diría que si trabajas dentro de un equipo para llegar a un estándar para que todos al menos codifiquen y comenten de la misma manera, así que mirar el código se vuelve más fácil.

Hago esto porque a menudo me comunico la intención o esencialmente pongo un marcador conveniente para cosas como "La limpieza de datos comienza aquí". Por lo general, debajo de ese título hay un breve resumen sobre la lógica de lo que estoy haciendo y por qué.

Me gusta la redundancia Si pierdo mi cuaderno de laboratorio por una razón u otra, o tengo que volver a visitar el código que escribí hace años, no me gusta tener que reconstruir lo que estaba haciendo y por qué lo estaba haciendo. Si al menos algo de esa lógica está en el código, está lo suficientemente documentado para que al menos pueda trabajar con él nuevamente.

Creo que parte de mi inclinación hacia él es que una buena parte de mi programación es de naturaleza estadística y, por lo tanto, algo repetitiva. Mientras que podría haber algunas piezas de código en las que tengo que buscar una función útilmente nombrada, podría tener varias docenas de usos bastante similares de algo así como una función de modelo lineal general. Es útil poder ir y encontrar cuál de ellos era el "qué tan sensibles son los resultados para el código de Elección A versus Elección B o C", y cuál era otra cosa. Eso a menudo se acelera por títulos.

Creo que es útil en situaciones en las que tienes archivos fuente gigantes con docenas de funciones y puedes organizarlos libremente en trozos como ese. Sin embargo, no digo que me guste más que los archivos fuente más pequeños y más enfocados ...