Comentar código fuera de delphi?

[[Lepe]]

Hola,

¿Conocéis alguna utilidad que pueda guardar los comentarios de un código fuente fuera del archivo .pas?

Uso Delphi 7.

El tema es que no quieren que el código esté lleno de comentarios, (projecto de más de 300 forms), estoy de acuerdo con ello, ya que el código debería ser autoexplicativo, pero en un proyecto que no he hecho yo, necesitaría anotar algunas cosas.

Ya sé que es algo raro, es más, había pensado el "hazlo tú mismo" con Cnpacks pero la sincronización del código con los comentarios no pueden ir por el número de línea y por el texto de la línea.... puede fallar.

¿Conocéis alguna utilidad?
Aparte de poneros las pilas ¿qué hacéis en estos casos?


Saludos y gracias de antemano por vuestro tiempo.

[dec]

Hola,

Sólo por dar una idea, yo una vez quise hacer algo parecido con código PHP y era posible usando PHPDoc. Ahora bien, PHPDoc se basa en JavaDoc, y, existe algo como DelphiDoc, que, también se basa en JavaDoc. La idea es que tú sólo incluyes una línea de comentario en determinado lugar, y, dicha línea lleva a un archivo XML que contiene la documentación de marras. De este modo, al generar la documentación, el programa en cuestión puede recoger la información del archivo XML y asociarla al lugar/identificador/clase o lo que sea.

Lo bueno es que se supone que no llenas el código de comentarios, pues sólo utilizas una línea. Lo malo es que debes mantener "sincronizados" el XML de cada comentario y el código fuente. Y otra cosa mala hay todavía, y, es que no sé si DelphiDoc soporta algo así, estoy echando un vistazo ahora mismo. No obstante no he querido dejar de decirlo, pues, es posible que otros programas de este tipo cuenten con dicha característica, es decir, sólo quería dar una idea de cómo sé que puede hacerse. No sé si valdrá de algo o qué.

Edito: Parece que DelphiDoc no está muy actualizado que digamos. Además he obtenido alguna "violación de acceso", y, con todo no he podido probar si soporta lo que he mencionado arriba o no. Tal vez algún compañero conozca de algún programa similar... yo quiero recordar uno que no era DelphiDoc, pero, no sé si era para PHP o si era para Delphi o si no existe y lo he soñado.

[Casimiro Notevi]

Lo que no comprendo es el motivo de no querer poner comentarios, ¿qué más da?, a ver si piensan que el programa va más lento por eso

No conozco ninguna utilidad que te sirva, y además veo difícil que exista, porque si no quieren comentarios, como mínimo se tendría que permitir usar "marcas" que sirvieran para enlazar con un fichero externo.
Pero si no quieren comentarios entonces es seguro que tampoco quieren "marcas".
Sería algo parecido a los bookmark, que se almacenan en un fichero aparte la línea, tú podrías incluir el comentario además de la línea. Pero claro, sería un fichero que tendrías que cargar en memoria cuando abres el proyecto e ir actualizando los números de líneas según se va modificando el fuente.
Algo engorroso, aunque posible.

[UFmain]
100  comentario djfdjfdsjfj fjdlfjd
314  eaff udfoauof mm..m.ww

[UFcuentas]
22  qerpueruwruewir rueoruwo
23  jdfjafj oiuoerjwelrjew
988  jdkejr ekrjerjejr

Lo complicado es sincronizar los números de líneas, seguramente antes de guardar el proyecto se buscaría el comentario y la línea en que está, sustituyéndola por la actual (la que está en el fichero externo)

Creo que he servido de poca ayuda.

[Neftali [Germán.Estévez]]

Empezado por Lepe

¿Conocéis alguna utilidad que pueda guardar los comentarios de un código fuente fuera del archivo .pas?

Empezado por Casimiro Notevi

Lo que no comprendo es el motivo de no querer poner comentarios, ¿qué más da?, a ver si piensan que el programa va más lento por eso

+1

Pienso igual que Casimiro.
¿Qué sentido tiene eliminar los comentarios del código?
¿Cual es el problema?

Si es por temas de legibilidad y estáis usando versiones nuevas, tal vez podríais usar la directiva REGION.

[[Al González]]

Creo que estamos ante un despropósito.

No encuentro la relación entre un proyecto con una buena cantidad de formularios y la necesidad de que su código no lleve comentarios. Al contrario, diría que entre más grande es un proyecto, más cuidado se debe tener de que esté debidamente comentado (aparte de la documentación externa al código fuente).

Eso del código autoexplicativo es un concepto con trampa. El código fuente es escrito en un lenguaje que está entre el entendimiento normal humano (un idioma) y la capacidad de análisis de un compilador o intérprete. Se escribe de tal manera que el humano pueda entenderlo, pero concediendo algunas facilidades para que el compilador o intérprete haga su trabajo.

En Delphi, por ejemplo, si escribiésemos el código fuente en inglés normal, sería muy complicado disponer de un compilador capaz de transformar el texto del programa en código máquina. En el otro extremo, si escribiésemos el código solamente con ceros y unos (para una asimilación automática por parte de la computadora), resultaría prácticamente imposible que un programador pudiera leerlo con plena comprensión.

Por ello es que siempre programamos en un lenguaje "intermedio": algo que el compilador pueda procesar, pero que también el humano pueda leer. Claro está, este código fuente debe escribirse de forma comprensible, pero por más claro y ordenado que se encuentre, en muchas ocasiones hará falta algo adicional para quien intente leer ese código fuente, así sea otro programador o el mismo autor tiempo después. Y ese algo adicional son precisamente los comentarios que acompañan al código.

Los comentarios resultan sumamente prácticos porque están ahí, justo al lado del código fuente (arriba, debajo, al costado). Un programador abre un archivo y debe ser capaz de entender (contexto previamente analizado) las sentencias de una rutina, por las sentencias mismas y, ante alguna duda o confusión, por los comentarios que ahí están. Incluso con frecuencia basta, es más rápido y requiere menor esfuerzo neuronal leer el comentario que se encuentra arriba de un If, que el If mismo con todas sus condiciones.

Un comentario fuera del código fuente no es un comentario, es documentación. Pero por más rica que sea la documentación, no se compara con la oportunidad de comprender un bloque de instrucciones debidamente comentado, in situ.

Lepe, yo buscaría convencer a quienes han solicitado eso de lo inadecuado que sería.

Buen martes a todos.

Al González.

[DarKraZY]

En alguna ocasión he pensado en algo parecido a lo que piden los superiores de Lepe. En mi caso, esa idea extrema, ha sido después de observar siempre los mismos comentarios tipo:

Código Delphi [-]
for i := 0 to 20 do
begin
//50 líneas dentro
end; // fin del for

O por el lío que genera no identar el código fuente, cabeceras al inicio del documento desactualizadas, etc.

Pero hay veces que es necesario hacer comentarios en el propio código fuente. Ahora mismo me acabo de encontrar con el problema de hacer DisableControls en una relación maestro/detalle entre dos TClientDataSet y he añadido un comentario para avisar de usar BlockReadSize.

En mi caso suelo utilizar subversión y con cada commit añado información de porqué he hecho modificaciones. No sé si eso te podría servir.

Saludos!

[[Lepe]]

Antes de nada quiero agradecer vuestros comentarios, como siempre, magníficos.

Neftali y Al González: Sí, es un despropósito, lo sé, pero es lo único que se me ocurre para salir del paso. En realidad son muchas cosas las que tenemos pendiente en el cajón (migrar a XE con Firebird 2.5, por ejemplo). El REGION me gustó del XE, ya me gustaría poder usarlo en D7 jejeje.

dec:: conocía de oídas el DelphiDoc, al ser Open Source, le echaré una visual.

Casimiro: Mi jefe es programador Delphi con más de 20 años de experiencia, único programador del proyecto. Creo es más bien una cuestión de gustos. No puedo dar más detalles, tampoco es que hayamos tenido una conversación larga y tendida sobre el tema, solo hizo un comentario y prefiero molestar lo mínimo. Esos comentarios a él no le sirven porque conoce TODO, (hasta la última coma) del proyecto [créeme, cuando digo hasta la última coma]. Mi idea es precisamente la que tú comentas, pero además del número de línea, guardaría un trozo de texto del código (con 1 Tera de Disco duro eso es lo de menos), así puedo abrir una ventanita de Cnpacks automáticamente mostrando el comentario en una ventana adosada (docked) o flotando donde no moleste.

DarKraZY: Uso Tortoise en un repositorio local, se lo he comentado, pero como no tenemos tiempo, no hemos sacado tiempo para ponerlo en marcha. Como tiene comprado el XE, en cuanto migremos el proyecto lo usaremos fijo. En realidad no me lo han pedido, es algo que quiero hacer para "aclararme yo".

Tengo que dejar aparcado esto un par de días, miraré las opciones más detenidamente.

Gracias y un Saludo.

[Casimiro Notevi]

Empezado por Lepe

Esos comentarios a él no le sirven porque conoce TODO, (hasta la última coma) del proyecto [créeme, cuando digo hasta la última coma].

Tendrá memoria fotográfica.

[Neftali [Germán.Estévez]]

Empezado por Casimiro Notevi

Sería algo parecido a los bookmark, que se almacenan en un fichero aparte la línea, tú podrías incluir el comentario además de la línea.

Lo complicado es sincronizar los números de líneas, seguramente antes de guardar el proyecto se buscaría el comentario y la línea en que está, sustituyéndola por la actual (la que está en el fichero externo)

No se me antoja nada sencilla.
Hay que tener en cuenta muchas cosas; Me parece bastante fácil que en un momento se "descuadre" esa relación e imagino la cantidad de trabajo perdido. Todo el fichero de comentarios quedaría invalidado, toda esa información perdida.

Por no decir qué pasaría si se utiliza algún sistema de control de versiones. ¿Dónde se guardarían esos ficheros? Habría que sincronizarlos también.
¿Qué pasaría con el fichero al hacer un Check-in/Check-out? Hay alunas herramientas que permiten adjuntar ficheros a uno de código o añadirlo a la misma familia (tal vez eso podría ser una solución), pero no se si todos tienen esa posibilidad.

[Casimiro Notevi]

Sí, fácil no sería, y las posibilidades de "estropicio" son muchas.
Pero es que lo fácil, rápido y cómodo es poner comentarios en el código. Si el jefe tiene memoria fotográfica, pues mejor para él, pero no puede exigir a los demás que la tengan. Algún día puede que sufra de alzeimer o que se pegue un porrazo en la bañera y se le olvide el código, ¿y ahora qué?

No quiero dar ideas, Lepe

[[Lepe]]

Por suerte para mí, él es usuario de este foro también.

[Casimiro Notevi]

Empezado por Lepe

Por suerte para mí, él es usuario de este foro también.

Pues entonces, mejor

Señor jefe de Lepe:
Venga, hombre, que no va a pasar nada por escribir comentarios, al contrario, todos sabemos que los comentarios enriquecen al código, le da personalidad, ayuda a su entendimiento y pasa por convertirse de "frio código" a "arte tecnológico". Le da valores humanos.
Además que en el momento de compilar desaparece y no ocupa lugar en el ejecutable generado, por lo que el programa final no se modifica en ningún aspecto, será igual de rápido, ocupará lo mismo y hará todo exactamente igual que lo hacía antes.
Hay otros factores a tener en cuenta, por ejemplo, señor jefe de Lepe: usted decide jubilarse ya, tan joven, y se va a una isla tropical y vivir la vida y deja encargado del código a Lepe, ¿qué hará él sin comentarios en el código?, él es bueno, eso ya lo sabemos, pero no tiene memoria fotográfica, sólo un pequeño porcentaje de la población goza de ese don.
Así que, resumiendo, que le deje poner comentarios, hombre, que no pasa nada.
Saludos de alguien que tuvo memoria fotográfica.

Espero que sirva de algo

[Neftali [Germán.Estévez]]

Empezado por Lepe

Por suerte para mí, él es usuario de este foro también.

Cuantos más seamos mejor... ;-)

A ver si se anima y nos da su opinión.

[roman]

A ver si no resulta que Lepe es su propio jefe

// Saludos

[[Al González]]

Empezado por Neftali

A ver si se anima y nos da su opinión.

No sin antes haber leído las nuestras.

Lepe, ¿ya le referiste este hilo a tu jefe?

[[Lepe]]

no, no quiero que me despida para contratar a alguien con memoria fotográfica

[Ñuño Martínez]

Acabo de comentarlo en otro hilo:

Empezado por Ñuño Martínez

Yo uso PasDoc, un programa al que le das los nombres de los archivos de tu paquete/programa, los analiza, extrae información tanto de las declaraciones como de los comentarios y te genera documentación en TeX, HTML y algún otro formato más. Aunque lleva tiempo sin ser actualizado, la verdad es que funciona muy bien. El único problema que tengo es que por defecto suelo trabajar con UTF-8 y no lo soporta muy bien, pero es realmente impresionante. Para que veas qué te vas a encontrar, échale un vistazo a la documentación de Allegro.pas, que genero con esta aplicación.

Ahora mismo no recuerdo si en su web hay ejecutable para Windows, pero sí está seguro el código fuente. Si no puedes compilarlo (lo escribió pensando en FreePascal), dilo y te paso mi ejecutable (es libre, así que no hay problema).