Comentarios divisionales / seccionales, ¿buenos o malos?

7

Conozco la tendencia general contra los comentarios que explican cómo funciona algo, y cómo es una buena idea usarlos solo para explicar por qué está haciendo lo que está haciendo, pero ¿qué pasa con el uso de comentarios como un medio para dividir el código?

Supongamos que tiene un script que hace un preámbulo, busca en un montón de registros, imprime los registros y luego cierra todo:

// Preamble
... preamble code, say about 10-15 lines ...

// Find records
... sql query ...
... put records into array ...
... some other stuff ...

// Print records
... printing records, 20-30 lines a record ...

// Close everything
...

Más de una manera de dividir visualmente el código, hace que sea más fácil encontrar una determinada sección. Como si en un mes necesitas corregir el código de impresión, en lugar de leer un par de cientos de líneas para intentar encontrar el lugar correcto, solo mira los comentarios para ver dónde está.

¿Qué sucede en realidad en cada sección que es bastante sencillo y fácil de explicar qué está pasando? ¿este enfoque de los comentarios se consideraría bueno o malo ?

Editar: Estoy trabajando principalmente con scripts PHP, donde o no puedes poner código en funciones, o no es práctico hacerlo. Sin embargo, el mismo tipo de cosa se aplicaría a archivos de clase grandes, con varios métodos que hacen cosas relacionadas, como captadores / configuradores, actualizaciones de bases de datos, etc.

    
pregunta Tarka 10.11.2010 - 16:14

6 respuestas

8

No están fuera, pero me gustaría preguntarte si tu rutina es tan larga que tiene secciones que son significativas por sí mismas y necesitan un comentario. ¿No sería mejor dividirlas en rutinas más pequeñas?

Luego tendrías una rutina de nivel superior que era totalmente legible sin comentarios:

Thing.Initialise
Thing.PopulateFromDatabase
Thing.PrintResults
Thing.ShutDown

Además, todo es reutilizable ahora.

También agregaría que, por lo general, cosas como "cerrar todo" deberían ser obvias por el código y la estructura y, por lo tanto, innecesarias. Si el código es This.Close (), That.CleanUp (), TheOther.Disconnect (), entonces realmente no necesita un comentario explicativo.

Donde creo que este tipo de comentarios son buenos es en el diseño y la estructura antes de comenzar. Encuentro que es bueno escribir la cosa en pseudocódigo en comentarios y luego eliminarla cuando la codifique. A continuación, puede agregar y modificar el diseño rápidamente, ya que está codificando sin el riesgo de olvidar lo que había decidido.

    
respondido por el Jon Hopkins 10.11.2010 - 16:23
7

Me gusta este tipo de comentario. No todo se basa en una clase o función separada. Por ejemplo, si tendría que pasar casi todo el estado del cuadro de pila a tal función / clase, realmente no estará desacoplando / simplificando nada al factorizar el código. Incluso si el código puede ser eliminado, eso no significa que deba ser. Debe sopesar las ganancias de reutilización y las mejoras en la legibilidad de los pasos individuales frente al hecho de que una indirección excesiva puede hacer que el flujo general del código sea más opaco.

Incluso si separa el código en una clase / función, los comentarios a veces pueden ser útiles para explicar a un alto nivel qué hace el código. Los comentarios no sustituyen al código legible, pero incluso el código legible no siempre resume su propósito de alto nivel, incluso si está bien factorizado en pequeñas funciones / clases.

    
respondido por el dsimcha 10.11.2010 - 17:40
1

Personalmente, estoy en contra de este tipo de comentarios, pero solo porque la mayoría de los editores de códigos modernos le permiten contraer métodos que facilitan la lectura. Por lo tanto, agregar comentarios tiende a ser un desorden, ya que ya no contribuye a aclarar nada, sino simplemente a declarar agrupamiento.

C # tiene una agrupación usando #region y #endregion que es útil. Eclipse hace un uso decente de un esquema.

Sin embargo, no hay una forma incorrecta de comentar el código y, en general, no es "peor" tener más comentarios (no voy a pretender que puedes codificar más rápido sin él).

    
respondido por el Neil 10.11.2010 - 16:25
1

Creo que estaría bien si tienes un código similar, por ejemplo. this.setProperty("prop", "val"); una y otra vez. Por lo tanto, podría tener un método init () que tuviera una sección de propiedades globales, propiedades locales e inicializadores de sesión. Sin embargo, aún los pondría en métodos separados a menos que NO hubiera ninguna posibilidad de que ese código pudiera ser reutilizado.

    
respondido por el Michael K 10.11.2010 - 16:38
1

En un entorno de script de procedimientos, donde todo el código está contenido en un archivo como subrutinas, los comentarios que describen las secciones de código serían obligatorios después de cierto punto, y no hay nada de malo en ello.

Actualmente estoy mirando un Applescript que tiene casi 700 líneas de largo y que está a punto de duplicar su tamaño aquí muy pronto (otros Applescripts que tienen más de 2000 líneas) con docenas de subrutinas. Mover el código a archivos externos es más problemático de lo que vale en este momento, por lo que comentar en la sección es la mejor manera de administrarlo todo hasta que encuentre tiempo para mejorar la situación.

Estoy basando mi respuesta en el hecho de que usted usó específicamente la palabra "script" en su pregunta, que contradice un script de procedimiento en lugar de un código orientado a objetos.

    
respondido por el Philip Regan 10.11.2010 - 16:22
0

Personalmente sería redundante. La razón es que si tuviera que crear una función o clase para manejar la tarea, entonces debería ser un prólogo directo para volver y hacer cambios en el futuro.

    
respondido por el Jeremy 10.11.2010 - 16:21

Lea otras preguntas en las etiquetas