Documentación del código

Moderadores: Kravenbcn, largeroliker, fidelcastro, cerealkiller, pspCaracas, dark_sasuke, m0skit0, LnD, ka69, zacky06

Avatar de Usuario
m0skit0
Administrador
Administrador
Mensajes: 5585
Registrado: 03 Sep 2009, 09:35
Ubicación: 0xdeadbeef

Documentación del código

Mensaje por m0skit0 »

Abro este hilo para discutir cómo podríamos incorporar documentación/comentarios al código. Sin ánimos de ofender, la forma en que lo hacíamos hasta ahora no me ha convencido del todo. Por ejemplo, muchos IDEs permiten ver la definición de la clase/método/atributo dejando el ratón encima, y así no se pueden ver los comentarios sobre el método. Además tal y como estaba planteado era incluso mejor tener la documentación en un fichero aparte. Estoy pensando seriamente en la opción de algo como JavaDoc (que alguien comentó anteriormente, no recuerdo ahora a quién).
Imagen

arisma
Habitual
Habitual
Mensajes: 497
Registrado: 18 Sep 2009, 08:41

Re: Documentación del código

Mensaje por arisma »

Es establecer una forma y o bien alguien que quiera desarrollar una herramienta tipo javadoc.

O aquellos que no se vayan a involucrar a nivel de programación, que preparen la documentación si quieren.

yosoy_bostero
Enteradillo
Enteradillo
Mensajes: 43
Registrado: 12 Ene 2011, 16:55

Re: Documentación del código

Mensaje por yosoy_bostero »

yo creo que estaria bueno otro tipo de diagrama (el que hiciste es bueno) o mas comentarios en el codigo, estuve menos de 2 dias sin leer y has avanzado un monton y a la vez rediseñado muchas cosas, se me esta complicando para seguir el proyecto, ya que solo puedo leer el codigo y tratar de entender la idea.

tal vez mas comentarios o otro diagrama de clases (con atributos y metodos) podria ayudar, ademas de algun comentario a nivel general de que es lo que se pretende con cada clase. Aparecieron muchas clases nuevas y se me complica el 'que hacen" voy a empezar con las consultas en el hilo del codigo fuente.

Avatar de Usuario
m0skit0
Administrador
Administrador
Mensajes: 5585
Registrado: 03 Sep 2009, 09:35
Ubicación: 0xdeadbeef

Re: Documentación del código

Mensaje por m0skit0 »

yosoy_bostero escribió:yo creo que estaria bueno otro tipo de diagrama (el que hiciste es bueno) o mas comentarios en el codigo, estuve menos de 2 dias sin leer y has avanzado un monton y a la vez rediseñado muchas cosas, se me esta complicando para seguir el proyecto, ya que solo puedo leer el codigo y tratar de entender la idea.

Es lo que suele pasar en este tipo de proyectos compartidos. Siento no tener tiempo para poner más comentarios, pero espero que estos días me ponga a comentar lo que ya está hecho antes de seguir codificando más, que al final soy yo el que va a olvidar qué hace cada cosa :lol:

yosoy_bostero escribió:otro diagrama de clases (con atributos y metodos) podria ayudar

Es que los diagramas llevan tiempo. Si se pudiera encontrar alguna herramienta de análisis de código que lo haga automáticamente, sería mucho más sencillo, y se podrían poner anotaciones sobre dichos diagramas. Si sabéis de alguna para C++ (tampoco me he puesto a buscar, pero tiene que haber) pues lo comentáis por el hilo de herramientas.

yosoy_bostero escribió:Aparecieron muchas clases nuevas y se me complica el 'que hacen" voy a empezar con las consultas en el hilo del codigo fuente.

Sí, cuando quieras te resuelvo las dudas que tengas. Y sí, tengo que poner más comentarios, no hay ni uno :lol: Es que me he cebado con la codificación :tongue:
Imagen

Avatar de Usuario
Yn$an€
Desarrollador
Desarrollador
Mensajes: 258
Registrado: 11 Feb 2011, 21:44

Re: Documentación del código

Mensaje por Yn$an€ »

Comento también los defines? Lo prefiero, si no te importa. La decisión final es tuya.

Edito: Y los métodos privados? Claro que éstos si encuentro como. :lol:

Reedito: Hecho. Busco paquete de generación de gráficos :mrgreen:

Reedito de nuevo: Bueno, los gráficos me van a dar trabajo :juasjuas: Bueno, los reportes son optativos, pero parece que hago algo smiles-plying_psp
... after all, we're all alike.

Avatar de Usuario
m0skit0
Administrador
Administrador
Mensajes: 5585
Registrado: 03 Sep 2009, 09:35
Ubicación: 0xdeadbeef

Re: Documentación del código

Mensaje por m0skit0 »

Cuanto más comentario, mejor, siempre que sigas la estructura que marca Doxygen (que es lo que estás usando, no?)

Saludos, gracias y ánimo :oki:
Imagen

Avatar de Usuario
Yn$an€
Desarrollador
Desarrollador
Mensajes: 258
Registrado: 11 Feb 2011, 21:44

Re: Documentación del código

Mensaje por Yn$an€ »

Si, si, Doxygen.

Gracias a ti. No veas como me lo paso. Comentando na más. Imagínate si codifico algo :mrgreen:
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Ésto lo traigo de otro post, para no mezclar más.
-----------------------
Pues a comentar se ha dicho. Te importa que me encargue de generar la documentación? Es un botón sólo. Incluso se puede crear un script para que haga todo. Ya tengo configurado el doxygen, que por otro lado lo da todo(casi) hecho ya con la GUI. El script sería sólo comparar y escribir las órdenes. La doc está en html por defecto. Se podría subir a googlecode?

Estoy haciendo que guarde copias de los archivos .h, que quedarán con los comentarios de línea simple.
Los comentaris explicativos de cada función se quedan en el .cpp y ésta será la fuente de las clases para doxygen. Así se queda todo lo bueno de las 2 cosas.
Un único problema: Molesta una cabecera con la descripción encima de cada método en los .cpp?


Ejemplo:

Explicación de los métodos en el indice de clases
Imagen

Captura de la copia de la cabecera que doxygen guarda
Imagen[/URL]

Snipet del fichero de código fuente

Código: Seleccionar todo

    /**
   *Todos los registros genéricos al valor por defecto
   */
tError cAllegrex::inicializarRegistros(void)
{

   int i;
   for(i = 0; i < NUM_REG_GENERICOS; i++)
   {
      regGenericos[i] = REG_VALOR_DEFECTO;
   }
(...............)
}


Mi pregunta es si prefieres la explicación detallada también en la cabecera, y el .cpp limpio para programar en el.

Espero que se entienda, y lamento el tamaño del post.

EDIT: Oye, pues lo dejaría así. Me gusta como hace una lista con los TODO y la función a la que pertenecen y como quedan las aclaraciones. Si te molestan, te hago un programa o un script que te los borre del código con el que trabajes. Pero con tiempecillo eh! (Aclaro, lo hago yo si es el caso porque sería culpa mía, obviamente no se trata de presumir ni hay nada de que hacerlo. Aclaro pa aquellos que lo lean de pasada )
... after all, we're all alike.

Avatar de Usuario
m0skit0
Administrador
Administrador
Mensajes: 5585
Registrado: 03 Sep 2009, 09:35
Ubicación: 0xdeadbeef

Re: Documentación del código

Mensaje por m0skit0 »

Wow, ¡excelente! :oki:

Yn$an€ escribió:La doc está en html por defecto. Se podría subir a googlecode?

Perfecto. Si te sabes manejar con SVN, te doy permisos de escritura y añades la documentación en un directorio doc por ejemplo.

Yn$an€ escribió:Estoy haciendo que guarde copias de los archivos .h, que quedarán con los comentarios de línea simple.
Los comentaris explicativos de cada función se quedan en el .cpp y ésta será la fuente de las clases para doxygen. Así se queda todo lo bueno de las 2 cosas.
Un único problema: Molesta una cabecera con la descripción encima de cada método en los .cpp?

No tengo problema en que los ficheros se queden con los comentarios, de hecho lo prefiero :oki: Tampoco hay problema con quedarnos con estos comentarios sustituyendo los antiguos. Tampoco molesta la cabecera, más bien al contrario :adora:

Yn$an€ escribió:Espero que se entienda, y lamento el tamaño del post.

Perfecto, y no hay que lamentar los tamaños de los posts.
Imagen

Avatar de Usuario
Yn$an€
Desarrollador
Desarrollador
Mensajes: 258
Registrado: 11 Feb 2011, 21:44

Re: Documentación del código

Mensaje por Yn$an€ »

Con un poco de tiempo para aprender y terminar de documentar todo, por mi vale. :D
... after all, we're all alike.

Avatar de Usuario
m0skit0
Administrador
Administrador
Mensajes: 5585
Registrado: 03 Sep 2009, 09:35
Ubicación: 0xdeadbeef

Re: Documentación del código

Mensaje por m0skit0 »

Perfecto, pues cuando quieras me mandas tu correo y te añado.

Saludos
Imagen

Responder