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)
Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License