Estándares

Introducción

• De la formación del personal se encargan los tutoriales, que no solo tratan de tecnologías específicas de cada grupo de trabajo sino también de todo lo necesario como el control de versiones. Todo el mundo documentará sus tecnologías, así minimizamos el riesgo de personal de que, en ausencia de alguien, nadie supiera cómo seguir su trabajo.
• El modelo de desarrollo a seguir para el código queda establecido como propuesta-modelo-desarrollo la propuesta inicial, disponible en los tutoriales.
• La evaluación de la calidad queda repartida entre todo el personal. Se repartirá a cada uno código a leer de otros grupos para revisar la legibilidad y concordancia a estándares del mismo. En cuanto a la documentación, Ezequiel queda como gestor último de la calidad de la misma, y se ruega a todo aquel que encuentre problemas en la misma que los solucione o al menos notifique.
• El estándar de documentación en wiki es sencillo: Todo aquello que vaya a ser incluido a posteriori debe empezar con el header de tamaño 2: ++, para que con el de tamaño 1 se pueda categorizar al incluirlo. A partir de ahí, se ruega la máxima legibilidad y corrección, así como la estructura que se considere adecuada mediante headers. Se ruega a cada equipo que documente en el wiki todo lo posible para tener constancia al final.
• Por favor, para mantener el nivel de calidad en la documentación usad el corrector ortográfico de firefox. Ahorraréis trabajo a control de calidad ;).
• Todo fragmento de documentación exigido por Gervás debe tener como padre (o abuelo, vaya) doc, como categoría doc: y debe comprobarse que queda incluido correctamente en printable (que no se rompe la anidación de headers, generalmente). Si no está allí, no se entrega al final…
• Para poner fragmentos de código se *debe* usar la etiqueta [code].
• Respecto a los comentarios, ya lo he mencionado en lista de correo: No dejéis comentarios entre la documentación, usad las páginas de comentarios de cada página y así los podemos ver juntos… Si echáis en falta la sección comentarios, añadidla con :
  

[[div class="comentarios" ]]
+++ Comentarios: [!--anidamiento según la página--]
[[module Comments title="" hide="true"]]
[[/div]]

Con esto solucionaremos el tema de flujo de información interna en el proyecto sin riesgos a la calidad de la documentación final (ya que al imprimir en PDF no se verá).

• El estándar de código seguirá estandar-codigo. Se escribirá lo más posible en inglés, para facilitar salidas posteriores a nuestro proyecto.

---

Modelo de desarrollo de código

Introducción

Tras estudiar un poco el funcionamiento de http://launchpad.net (no tan intuitivo como pretenden), he aquí una propuesta de modo de trabajo "con-código" para cuando tengamos que tirar líneas.

Los tutoriales concretos de bazaar siguiendo este modelo están aquí.

Ejemplo

Para resumir muy mucho, como algunos sabréis bazaar es un sistema de control de versiones que sirve igual que la historia de la wiki: lleva todas las versiones de tus archivos de código (en realidad de cualquiera), te enseña las diferencias entre versiones y te permite hacer otro millón de cosas interesantes como trabajar mucha gente a la vez (como subversion, pero sin necesidad de un server central), o mezclar bien los cambios entre el trabajo de mucha gente (lo más automático posible: si dos escribimos distinto una línea obviamente hay que revisar a mano, esto no es IA). Bazaar puede trabajar en modo "checkout", donde es básicamente "subversion" (el server centralizado, cuando cambias algo detecta tus cambios y tienes que mandarlos al repositorio remoto con "commit", y bajarte los cambios de otros con "update" antes de trabajar), pero también puede hacer "branch" (o "ramas", que son como "variantes" de una base de código con tus modificaciones por entendernos) con lo que todo se almacena en local, y para juntar tu código con otros branches hay un comando "merge" entre branches separados (parecido, supongo, al svn merge).

ojo que los comandos no son exactos, sino cogidos de los equivalentes en subversion.

Basamos el modelo de desarrollo en la propuesta de separarnos en grupitos de desarrollo con los que organizamos un poco.

Modelo de desarrollo

INDIVIDUO

• Absolutamente opcional. Para que la gente que no se aclare con el bazaar no tenga que liarse más de lo estrictamente necesario. Esto sirve solo para facilitar al trabajo al que se quiera complicar un poquito la vida al principio, es útil cuando eres desorganizado como yo.
• Trabajar en local con bazaar, y descentralizado.
• Puedes hacer commits locales (esto es, *sin* conexión a internete). Pero también puedes subir tu código a tu espacio de launchpad con bzr push, para bajarte el código desde la facu, sincronizar con tu portátil, tener un cierto backup o lo que sea. Sin embargo al no necesitar conexión para hacer commits puedes hacerlos frecuentemente (casi con cada cambio que hagas que ande a medias, vamos), y tienes "time machine" de tus archivos de código (de eso va el commit tb, puedes hacer "revert" y deshacer cambios).
• Puedes usarlo para otros proyectos tuyos, tener cienmil branches del código
• Como contra, hay que *aprender* a usarlo.
• Aquí es donde tiras tus líneas de código.

EQUIPO

• Los cuatro equipos del apocalipsis XD.
• Separación de trabajo por bloques de funcionalidad, o como podamos o queramos repartírnoslo.
• Cada equipo agrupa features del código, probablemente inestables y rotas, mientras se desarrollan.
• Trabajamos con el modelo "checkout" que es trabajar *igual* que en subversion, los commits son *solo* remotos.
• Dos opciones de trabajo:
  1. Si trabajas con bazaar en local, tus branches locales llevan tu código y su historia, y por tanto tienes que hacer merge de tu código personal con el branch del equipo (lógicamente, hay que sincronizarlo). En principio no debe ser mucho lío (nada que ver con subversion al respecto), pero esto es lo que habría que aprender realmente. Pero a cambio solo te hace falta conexión para sincronizar tu trabajo con el equipo, y puedes ir sincronizando más a alto nivel (cuando algo te medio funciona como para que el resto puedan usarlo, no una-vez-por-cada-cambio-en-archivos).
  2. Si pasas de liarte con bazaar en local, pasas a trabajar totalmente como si fuera subversion. Pierdes los commits locales y necesitas conexión (constante) a internet para cada commit, y pierdes también la posibilidad de hacer tus branches del branch del equipo (maldad extrema). A cambio, no te lías con merge y es muy similar a usar subversion, con el que algunos ya hemos trabajado.
• Aquí centralizamos el curro de cada equipo.
• Comentario: no es necesario un equipo *por feature*, en realidad para eso están los branches… Si os dais cuenta todos los equipos suben al *proyecto* hdlorean (lo veréis enseguida!), y en la página del proyecto quedan tanto los branches personales como los branches de equipo registrados, que pueden ser varios (se ve quién los publica, el equipo, y los nombres de esos branches, que sí pueden ser por feature).

PROYECTO

• Donde tenemos el proyecto ya todo junto.
• El "trunk" que viene por defecto en launchpad.
• Probablemente con sus propias branches (p.e. entregas a tal y cual fecha -se puede hacer con un tag-, estable, inestable, etc. ).
• A diferencia de los de equipo, feature-complete.
• Sirve para *integrar* el curro de los equipos: Aquí aplicamos control de calidad, los responsables de equipo (o team leaders que suena como más pijo) nos encargamos de mergear lo que sea, Mario controla que funcione como deba. El caso es que solo entre el código funcionando y se mantenga así lo más posible.
• Sería como un branch "de integración".
• nuevo: Usamos dos niveles de integración: en testing nos dedicamos a control de calidad y estabilizar código, mientras que unstable es para mezclar código entre repositorios separados y poder probarlo integrado. Todos los repositorios de equipo, por tanto, heredan de unstable y son mergeables con él.

Justificación

Como digo todo esto es un poco teórico porque no sé seguro si bazaar nos dejará hacerlo todo, pero creo que al menos sí bastante de ello. Así todo junto parece un follón, pero es solo para aclararnos. A la hora de la verdad se podría trabajar contra el checkout del team como quien curra con subversion, y solo hay problemas a la hora de integrar cambios entre todos. La contrapartida es que los desarrollos son separados, no hay problemas de tu-cambio-ha-roto-nuestro-código-en-otra-parte, etc.

Para entendernos: a la hora de la verdad, puede quedar en que tú subes tu código al branch de tu equipo, y luego solo nos peleamos un poco más los responsables con bazaar para integrarlo. Que es, por otra parte, quienes han confirmado que están dispuestos a trabajar así (al fin y al cabo somos quienes sufrirán un poco más para integrarlo). Para mayores problemas, recurriremos a Adrián como director de integración, o a Ezequiel como persona más informada en la tecnología.

Las ventajas de tener todo en launchpad es que cuando hay bugs se pueden relacionar con *todas* las partes afectadas por un bug a la vez (p.e. tu branch personal si trabajas con bazaar, a la vez el branch del equipo, y el proyecto que es donde apareciese). Puedes arreglar en *un* sitio y propagar los cambios a *todos*, o arreglar diferente en "estable" (con un parche cerdo XD) y en "inestable" (cambiando en plan serio lo que hubiese que cambiar). IDEM para peticiones de features, o lo que sea. Y el bugtracking así es más sencillo.

Otras "historias" de esto pueden ser p.e. que un equipo necesite un feature de otro equipo y estén ocupados con alguna otra prioridad, o lleve mucho tiempo implementarlo. Puedes o bien pedírselo amablemente, o bien implementarlo tú lo mínimo posible para que funcione y luego en el merge quitar tu implementación (ya bien sea en el merge hacia-proyecto o pillando trozos del código del otro equipo cuando está funcionando ya), o incluso implementarlo tú entero y que luego sea el equipo "responsable" de ese código el que lo pille de tu branch y lo mergee con el suyo.

---

Estándar de código

Consideraciones generales sobre el código

1. El código se escribirá íntegramente en inglés a fin de mejorar la distribución de nuestro proyecto como software libre.
2. Los identificadores no deben contener más de 15 caracteres y deben ser lo más significativos posible.
3. El código se sangrará adecuadamente y siempre mediante uso de tabuladores.
4. El desarrollador debe perseguir la eficacia de su código, sometiendo esta a los criterios de legibilidad y eficiencia. En este orden. Es decir, que funcione bien, que cualquiera lo pueda entender y, por último, que funciones rápido.
5. Los que uséis eclipse, al crear un nuevo proyecto, marcad la opción python 2.4 (la que hay en los laboratorios) o, si usáis otro editor, procurad no usar features de python 2.5
6. Para el tema de licencias: hay que incluir en la cabecera de cada archivo nuevo:

#Copyright (C) 2008 autores-del-código

#This file is part of HDLorean.
#
#HDLorean is free software: you can redistribute it and/or modify
#it under the terms of the GNU General Public License as published by
#the Free Software Foundation, version 2 of the License.

#HDLorean is distributed in the hope that it will be useful,
#but WITHOUT ANY WARRANTY; without even the implied warranty of
#MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
#GNU General Public License for more details.

#You should have received a copy of the GNU General Public License
#along with HDLorean.  If not, see <http://www.gnu.org/licenses/>.

Clases

1. Los nombres de las clases siguen la convención UpperCamelCase.
2. Las clases deben incluir comentarios Doxygen indicando su función, autores y responsables de mantenimiento.
3. Se declararán en primer lugar los miembros privados, y en segundo lugar los públicos.
4. De la misma manera, se declararán previamente los atributos y posteriormente los métodos.
5. Se aconseja declarar los constructores y destructores antes que cualquier otro método público.

Miembros de clase

1. Todos los miembros de clase, tanto públicos como privados siguen la convención lowerCamelCase. precedidos de guión bajo "_". (Por ejemplo, _privateMethod() o _privateVar)
2. Todo miembro debe incluir comentarios Doxygen. Los siguientes campos son obligatorios:

• Descripción breve. Se seguirá la convención propia de Javadoc, por la cual se considera descripción todo aquello que se encuentre antes del primer punto.
• Descripción detallada.
• Autor/es.
• Parámetros de entrada (si procede).
• Parámetros de retorno (si procede).
• Excepciones lanzadas (si procede)
• Referencias a otros métodos involucrados (si procede).

Comentarios

1. Los comentarios que conforman la documentación del código, se escribirán íntegramente en Inglés. Quedan exentos de esta regla aquellos con carácter temporal.
2. Los comentarios deben otorgar una descripción clara y concisa sobre la entidad descrita.
3. El código sin comentarios no será aceptado y se devolverá al autor para que lo comente adecuadamente.

Convenios adicionales sobre comentarios

Algunos grupos de desarrolladores, como KDE, utilizan algunos convenios para marcar partes del código que necesitan ser revisadas más adelante.

1.- Fixme

Indica que el código debe ser arreglado, puesto que el actual o bien no funciona correctamente, o bien no es legible, o bien no cumple el estándar de código establecido.

 // FIXME: breve descripción de por qué hay que arreglarlo

2.- Remember

Indica algo que debe recordarse acerca de un fragmento del código.

 // REMEMBER: breve descripción del recordatorio

3.- TODO

Indica alguna tarea pendiente de implementación.

 // TODO: Breve descripción de la tarea por hacer

Convenios adicionales para comentarios C++

Para comentarios en línea, se hará uso de la forma:

// Comentario de linea

Para comentarios de bloque se hará uso de la forma:

/* Comentario de
    bloque
*/

Para comentarios Doxygen se hará uso de la forma:

/**
    Comentario de
    documentación Doxygen
*/

Excepciones

1. Las excepciones suponen un deterioro del rendimiento, pero son necesarias en proyectos grandes como HD Lorean para gestionar de manera controlada situaciones excepcionales o errores.
2. Todas las funciones que lo precisen deberán usar excepciones
3. El desarrollador del método creará las excepciones que sean necesarias para el buen funcionamiento de su código.
4. Se desaconseja el uso de métodos cuyo valor de retorno sea el estado de éxito o fracaso de la operación. Para este tipo de situaciones es preferible hacer uso de excepciones.

Optimizaciones (Regla de Oro)

1. No optimices…
2. …todavía. (sólo expertos)

---

Estructura del wiki

• doc (categoría, pero no página): documentación relativa al proyecto concreto HD Lorean (arquitectura, casos de uso, etc).
  • doc:printable: Página que incluye todo. Conforma la entrega final de Junio, así que incluye incluso las entregas parciales (para dejar constancia de nustro trabajo). Para ello, hace includes de varios niveles (por ejemplo incluyendo gestion solamente, que a su vez incluye las planificaciones y demás), lo que simplifica su complejidad y reduce su tamaño.
  • doc:printable-MES: Hay un printable por entrega desde Noviembre. Como mínimo, incluyen la planificación de la iteración siguiente, y el seguimiento de la de ese mes; también incluyen las páginas nuevas creadas durante esa iteración. No van incluidas en la entrega final (porque sería duplicar trabajo); no obstante, podemos entregarlas aparte como complemento a esa documentación "integrada".
• gestion: documentación relativa a la gestión del proyecto, que sería reutilizable para futuros proyectos del grupo de desarrollo. Estándares de código, dónde está todo en el wiki, criterios de calidad, planificación seguida, etc.
  • gestion:estandares: Centralización de los principales estándares seguidos.
  • gestion:planificacion-fase: Quién hace qué y cuándo, ideas a grosso modo de cómo trabajaremos durante el mes. Con enlaces (pero no includes) a las iteraciones.
  • gestion:planificacion-iteracion-MES: Planificaciones concretas para cada mes.
  • gestion:seguimiento: Seguimiento general del proyecto (del plan de fase).
    • gestion:seguimiento-mes: seguimiento de cada iteración individual.
• tutoriales: documentación interna para la formación del personal en las distintas tecnologías.
• template (categoría): Plantillas útiles para crear paginas que se quiera consistentes entre sí (cada doc:printable, cada planificacion-iteracion-mes, etc).