Capítulo 4: Pautas de Desarrollo

Este documento describe las convenciones usadas en el proyecto Bluefish para escribir código. Por favor, sugieran mejoras o agregados.

Esto no_significa poner obstáculos a tu código sino que sirve para estructurarlo un poco. Por el momento, Bluefish no está muy bien estructurado y actualmente estoy tratando de mejorar esto un poco.

¡Feliz Programación!
Olivier Sessink
http://bluefish.openoffice.nl/

Depurando a Bluefish

Cuelgues - viendo el estado de la pila: backtrace

Para hacer un seguimiento útil y si no tienes idea dónde se cuelga el programa, ve al directorio de los archivos fuente y ejecuta el siguiente comando: make distclean ./configure --with-debugging-output make gdb src/bluefish Esto iniciará el depurador con el binario recién compilado. Si no tienes ninguna idea abre el archivo, agrega la siguiente línea en la parte superior #define DEBUG y ejecuta make distclean ./configure make gdb src/bluefish Una vez que se inicia el depurador presiona r<enter> si se detiene la ejecución o c<enter> si dice que no esta permitido leer la memoria. Corre el programa hasta que se cuelgue, entonces ejecuta bt<enter>. Envía la salida (digamos las últimas 50 líneas) a la lista de correo de desarrollo. Esto nos dará alguna información de depuración y nos dirá exactamente donde se localiza la falla en el programa.

El Sangrado y el Formato

Sé perezoso y usa cd src indent -kr -ts4 *.c *.h Esta es la convención que usa Kernighan & Ritchie con ancho de tabulación 4

No uses comentarios tipo C++ sino usa el de C /* y */. gcc hace las cosas bien pero otros compiladores C pueden llejar a quejarse.

Los Nombres

usa void name_cb() para una retrollamada (callback) que puede ser usada en forma global como, por ejemplo, una retrollamada para comenzar un diálogo (también puede ser cualquier cosa de allí el void)

usa static void name_lcb() para una retrollamada local como, por ejemplo, el botón OK de un diálogo (también puede ser cualquier cosa de allí el void)

trata de que el nombre de la función sugiera lo que puede hacer, por ejemplo, doc_do_replace() haría un reemplazo en un documento determinado, etc.

Actualmente poseemos un estándar para el document.c. Todas la funciones que empiezan con doc_...() tienen un parámetro Tdocument. Todas las funciones sin él o bien son antiguas (y por lo tanto se las deberían renombrar) o son funciones que funcionan como un main_v->current_document (un puntero al documento actual mostrado).

Declarando Procedimientos

Siempre declarar a las funciones estáticas que no necesitan ser vistas fuera del archivo como static. La razón: evitar contaminar el espacio de los nombres globales. Las funciones estáticas serán enlazadas con el mismo fle. Todos los procedimientos que se usan en otros archivos (públicos) deben figurar en el archivo .h declarado.

Todas las variables que se usen en otros archivos (públicos) deben figurar en el .h precedidas por extern. Sin embargo, trata de evitar el uso de variables globales. La mayoría de las veces esto se puede hacer declarando una estructura typedef.

No pongas ningún extern bla() al principio de un archivo .c file, usa en cambio #include otherfile.h. Así si cambias una función sólo tendrás que modificar ese archivo .h en particular. En otras palabras, declara las funciones globales en los archivos .h y en ningún otro lado.

Los Archivos de Cabecera

Si incluyes un archivo de cabecera tal como #include <string.h> por favor, agrega un comentario explicando por qué se necesita dicha cabecera. Algo así #include <string.h> /* strlen() */

Archivos Nuevos

Si estás escribiendo un archivo .c nuevo, escribe también un archivo .h e inclúyelo en él. Usa include guards en todos los archivos .h como en bluefish.h

#ifdef __BLUEFISH_H
#define __BLUEFISH_H
... poner todas las declaraciones aquí ...
#endif

La razón: permitir que el compilador verifique la consistencia entre los archivos .c y los .h

Los distintos archivos

Listado en orden alfabético

Parches

Antti-Juhani Kaijanaho escribió:

  1. Conservo dos estucturas jerárquicas diferentes de Bluefish: una sin tocar (la pre-oficial) y otra que uso para trabajar. Por cada cambio introducido creo una nueva estructura jerárquica.
  2. Antes de crear un parche ejecuto "make distclean".
  3. Cuando quiero crear un parche, me posiciono en el directorio padre de las dos estructuras jeráquicas. Luego ejecuto "diff -Naur pre_estructura_oficial mi_estructura_modificada | bzip2 -9c > patchbla.diff.bz2" (donde de pre_estructura_oficial y mi_estructura_modificada son las dos estucturas jerárquicas).

Uso del CVS

Olivier escribió:
Usar bash (rellenar con el propio nombre de usuario):

CVSROOT=:pserver:USERNAME@cvs1.openave.net:/home/cvsroot/bluefish1
export CVSROOT
cvs login
cvs checkout bluefish
esto descargará la versión más actual en desarrollo de Bluefish. Si ya has hecho esto antes puedes ejecutar
cvs update -dP
para actualizar tus archivos locales con los nuevos cambios. Para enviar los archivos:
cvs commit

enviará tus nuevos cambios al repositorio CVS. Por favor, siempre actualiza justo antes de hacer un envío, para comprobar si otras personas estan trabajandos sobre el mismo código fuente

Pueden resultar útiles algunos comandos másl:

Lineamientos del CVS

Antti-Juhani escribió:

Este plan de lanzamiento de tres etapas, según el modelo seguido por Debian, tiene en cuenta los desarrollos inestables paralelamente a la preparacíon del lanzamiento.

Para crear una rama:

cvs tag -b nombre_rama
Observemos que el árbol donde se hizo cvs tag sigue siendo el tronco, no la rama. Se necesita luego verificar una nueva copia de la rama:
cd algún_lugar
cvs checkout -r nombre_rama
Haciendo el envío a esta copia de trabajo equivale a hacerlo a la rama dejando el tronco sin tocar. Otras personas pueden acceder a la rama haciendo lo mismo.
cvs checkout -r.
Cuando quieres agregar tus cambios al tronco haz lo siguiente
cvs update -j name_of_branch

en el árbol original (el tronco). Arregla cualquier conflicto y envíalo.

Traducciones

Roland Steinbach (roland@ratisbona.com)escribió:
si deseas comenzar, por ejemplo, con la traducción al griego (gr) debes:

En futuras versiones si necesitas actualizar el archivo .po tienes que: ¡Eso es todo!

Algunos trucos

Nuevas versiones

Cosas para hacer en las próximas versiones:

... Tengo que terminar esto.

Enlaces útiles