Sondeo sobre la biblioteca GH Freebrary

[[AzidRain]]

Son muy buenas rutinas, y el código es bastante elegante y bien diseñado. Sin embargo lo que creo que le faltaría para redondearla es documentar un poco cada función y procedimiento ya que en efecto se puede deducir que hace cada una pero normalmente hay que leer un poco el código hasta lograrlo. Bastaría con una descripción sencilla de que hace o en que mejora a otra función de Delphi.

Se entiende la falta de documentación porque Al no estaba pensando en distribuirlas cuando las creó, entiendo que la biblioteca es el fruto de horas y horas de experiencia y trabajo que él amablemente nos regala.

[[Al González]]

Empezado por AzidRain

[...] Bastaría con una descripción sencilla de que hace o en que mejora a otra función de Delphi.

Desde luego, César. Mira, he estado publicando en el propio foro la documentación oficial:

http://www.clubdelphi.com/foros/showthread.php?t=84417

Lo sé, hasta ahora son pocos temas, pero confío en que lograremos (los incluyo a ustedes) documentarla por completo.

Por otra parte, veo que este hilo lleva 157 visitas y sólo cinco votantes. ¡Venga esa participación!

[[fjcg02]]

Yo no respondo porque no tengo esa versión de Delphi.

Lo que sigo insitiendo es que bajo mi punto de vista es fundamental varios ejemplos empleando las rutinas explicando cómo se utilizan y porqué. La descripción de lo que hacen las funciones o métodos me parecen un poco "pobres".

Creo que los desarrolladores buscamos código funcional, que resuelva algún problema específico. Algunos lo fusilan tal cual y otros lo adaptan a sus desarrollos. Sobre todo para la gente que empieza, puede ser la mejor forma de que adopten esta biblioteca para sus desarrollos.

Y respecto a los ejemplos, explicar brevemente cuando y porqué se ha de utilizar una solución que incluya componentes de esta biblioteca.

Un saludo

[[Al González]]

Empezado por fjcg02

Yo no respondo porque no tengo esa versión de Delphi.

Hola Javier. Tengo entendido que usas la versión 6. ¿Has considerado actualizarte a una versión más nueva? ¿Crees que valdría la pena adaptar GHF a Delphi 6? Creo recordar que algo de eso comenzaste a hacer hace poco tiempo. Si quedó funcional no estaría de más compartirla.

Empezado por fjcg02

[...] bajo mi punto de vista es fundamental varios ejemplos empleando las rutinas explicando cómo se utilizan y porqué. La descripción de lo que hacen las funciones o métodos me parecen un poco "pobres".

Para la documentación he intentado seguir un esquema similar al de las clásicas ayudas de Delphi y la API de Windows que en mi opinión son todo menos pobres. En las cuales se presenta: una descripción corta, la declaración del elemento, una descripción general, la descripción de cada uno de los parámetros, las notas u observaciones y algunos ejemplos.

Empezado por fjcg02

Creo que los desarrolladores buscamos código funcional, que resuelva algún problema específico.

Espero podamos avanzar en el entendimiento y documentación de la biblioteca para que su funcionalidad quede más visible.

Empezado por fjcg02

Y respecto a los ejemplos, explicar brevemente cuando y porqué se ha de utilizar una solución que incluya componentes de esta biblioteca.

Eso es algo que ya se viene haciendo en cada tema publicado, pero intentaré mejorarlo. La respuesta general a por qué usar algún elemento de cualquier biblioteca es porque resuelve algo o de forma más rápida, o escribiendo menos código, o con menos esfuerzo (o una combinación de las tres), que si no lo usáramos.

Tienes el caso de la clase TghForm, palabra que con solo ponerla en lugar de TForm al inicio de las declaraciones de formularios —cambiando "TForm1 = class(TForm)" por "TForm1 = class(TghForm)"—, nos facilitamos el manejo de dichos formularios (y los que deriven de ellos):

Empezado por Al González

Para dar una muestra, me gustaría explicar brevemente que cuando derivamos nuestros formularios de TghForm en lugar de TForm, seguimos contando con todo lo que trae de herencia TForm, pero podemos lanzar los formularios sin tener que crear y destruir nosotros mismos las instancias de éstos. Con una sola línea se crea, se ejecuta (abre) y, cuando el usuario lo cierra, se destruye el formulario:

Código Delphi [-]
TForm1.Execute;

No necesitamos preocuparnos de instanciar la variable del formulario, ni de liberarla después de usar éste. Execute es como ShowModal, pero haciendo el trabajo completo. Y, como ShowModal, devuelve un estado mrOK, mrCancel, ..., según la manera en que haya sido cerrado el formulario. Además puede recibir parámetros abiertos, por si queremos indicarle algo a nuestro formulario:

Código Delphi [-]
TForm1.Execute ('Rueda');
TForm1.Execute ('Palanca');

El formulario puede "recoger" esos parámetros en alguno de sus eventos, como el evento OnCreate:

Código Delphi [-]
procedure TForm1.FormCreate(Sender: TObject);
begin
  // Agregamos al título del formulario "Rueda" / "Palanca" (lo que se haya puesto en Execute)
  Caption := Caption + ' - ' + OpenParams [0];
end;

Y si queremos algo similar a Execute, pero que en lugar de hacer ShowModal abra el formulario como lo hace Show, entonces tenemos para ello el método Open:

Código Delphi [-]
TForm1.Open ('Rueda');

Agradezco mucho tu crítica, Javier. Más por haberte tomado la molestia de descargar, examinar y probar algunas partes de GH Freebrary, lo cual me consta por la correspondencia que hemos tenido. Ojalá vengan muchas otras de esas constructivas observaciones.

Un saludo.

Al.

[[fjcg02]]

Hola Al,
No era consciente de que mi comentario ibas a tomártelo tan en serio

Respondiendo uno a uno los puntos que comentas.

La versión que uso es la 7, y no creo que cambie la misma hasta dentro de bastante o hasta que cambien las condiciones que me rodean.

Respecto a la documentación que estás construyendo, me parece interesante e importante, pero ya he comentado otras veces que bajo mi punto de vista falta una pequeña aplicación que ponga en práctica todas las piezas del puzzle, bien comentada, sin que sea una superaplicación, sino que exponga de forma general el motivo de utilizar así las piezas.

Creo que con esto respondo a todos tus comentarios.

Desgraciadamente, en general no disponemos del tiempo que quisiéramos para investigar, probar,... e incluso hacer testeos en profundidad de bibliotecas como gh. Por eso indico que hacer el camino "más fácil" puede facilitar la utilización de gh.
Por otro lado, a algunos entre los que me incluyo, hemos necesitado de alguna parte de las soluciones que ofrece gh, que hemos utilizado o no. Si encontramos más ejemplos de cómo aprovecharnos de las bondades que ofrece, será más fácil que nuevos usuarios se suban al carro.

Por poner un ejemplo, las devE xpress son librerías muy apreciadas, por un lado por ser muy buenas, y por otro y no menos importante, estar bien documentada con muchos y buenos ejemplos. También influye tener un buen soporte, obviamente, pero juega en otra liga. Ahora, si una biblioteca cuaja, siempre hay alguien al que preguntar que ha resuelto las dudas de los usuarios.

Es todo lo que quería comentar. Me cojo unos días de vacaciones y desconectaré, pero intentaré retomar gh a ver sí puedo aportar algo a la vuelta de las mismas.

Un abrazo

[Ñuño Martínez]

En cuanto a la documentación, ¿has probado pasdoc? Yo lo uso con Allegro.pas y va de maravilla. Además, facilita coger la costumbre de documentar al mismo tiempo que estás escribiendo el código, lo cual es lo mejor que puede hacerse.

[[Al González]]

Empezado por Ñuño Martínez

En cuanto a la documentación, ¿has probado pasdoc? [...]

Te soy sincero, Ñuño, no me convence la idea de usar documentación automatizada, creo que eso reduciría la "estética" del código y dificultaría su manejo. Además, todos los comentarios que van en el código fuente los escribo en inglés, aunque a veces me lleva eternos minutos redactar unas cuantas líneas que le parezcan aceptables a quienes hablan ese idioma. Si bien puede ser difícil al principio, considero que lo anterior es algo que debería procurarse con cualquier biblioteca de programación de uso público: usar el idioma inglés tanto para el código fuente como para los comentarios que van en él.

En cambio para la documentación o "manual de referencia", como ya has notado, uso el castellano. No me considero capaz de escribir algo tan formal en el idioma de Mark Twain; ya llegarán —espero— varios samaritanos que comprendan el español leído, sean diestros en el inglés y aporten cinco o diez horas de su valiosa vida ayudando a traducir el manual.

Por otro lado, creo que utilizar el propio foro para la documentación ofrece varias ventajas, como es un adecuado formato de presentación, la disponibilidad pública en la Red y la retroalimentación con los usuarios. De hecho me extraña que hasta el momento nadie más haya publicado alguna biblioteca en el nuevo foro.

Saludos.

P.D. 334 visitas y sólo seis votantes...