it-swarm-es.com

¿Escribe títulos en comentarios de código?

Estaba hojeando un código antiguo que escribí (primer año en la universidad) y noté que solía escribir títulos de comentarios antes de 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 muy claro, pero mientras escaneaba el archivo me sorprendió lo mucho que me sentí como si supiera lo que está pasando aunque apenas miré el código real. Definitivamente puedo ver esto como apropiado en ciertas circunstancias, así que me pregunto, ¿haces esto? ¿Crees que es buena idea? ¿O es demasiado?

17
EpsilonVector

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

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

24
Maniero

Hago eso todo el tiempo. Tanto para marcar lo que está haciendo el código, como 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, escribo un proceso involucrado en los comentarios y 'completando' el código debajo de los comentarios a medida que avanzo.

13
GrandmasterB

Me parece interesante la cantidad de personas que no les gusta la práctica sin realmente poder articular por qué. La razón por la que comentarios como ese están mal vistos es que son una señal de que ha 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, en todo caso. De hecho, algunos profesores exigen su infracción para facilitar la calificación al agrupar todo en un solo archivo. Por lo tanto, su ignorancia de primer año es excusable, y el hecho de que haya notado "algo" mal y traté de aclarar con comentarios es incluso loable dadas las circunstancias, pero en general es mejor arreglar un diseño poco claro en lugar de tratar de taparlo con comentarios.

6
Karl Bielefeldt

Veo estas cosas como una forma de hacer que el código sea más claro o no. Si puede saber en base a los métodos en el archivo qué es cada parte, entonces no hay necesidad, sin embargo, si tiene tener múltiples secciones, entonces puede ser útil. Quizás cuando un archivo de código se vuelve demasiado grande, es necesario desglosarlo, lo que podría reducir la necesidad de tales comentarios.

Yo diría que si trabajas dentro de un equipo para llegar a un estándar, al menos todos codificarán y comentarán de la misma manera, de modo que mirar el código sea más fácil.

4
aqwert

Hago esto porque a menudo me comunico la intención a mí mismo, o esencialmente coloco un marcador conveniente para cosas como "La limpieza de datos comienza aquí". Por lo general, bajo ese título hay un poco 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 revisar 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 como para que al menos vuelva a trabajar con él.

Creo que parte de mi inclinación hacia esto es que una buena parte de mi programación es de naturaleza estadística y, por lo tanto, algo repetitiva. Si bien puede haber algunos fragmentos de código en los que tenga una función con un nombre útil para buscar, podría tener varias docenas de usos bastante similares de algo como una función de modelo lineal general. Es útil poder ir y encontrar cuál de esos fue el "qué tan sensibles son los resultados al código de la opción A frente a la opción B o C", y cuál fue otra cosa. Eso a menudo se acelera con los títulos.

3
Fomite

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 estoy diciendo que me guste más que los archivos fuente más pequeños y enfocados ...

2
µBio