DirectricesPyragua – Pyragua

  1. Directrices de Desarrollo de Pyragua
    1. Participando en el desarrollo de Pyragua
      1. Listas de Correo
    2. Documentación y Teoría
    3. Licencia de Pyragua
    4. Guía del código
    5. Estructura del repositorio
    6. Directrices para el código fuente
      1. Identación
      2. Nombres
      3. Comentarios
      4. Documentación
      5. Excepciones
    7. Convenciones para los mensajes de error
    8. Otras convenciones
    9. El ChangeLog
    10. Tests con PyUnit?
      1. Escribiendo los tests antes de codigicar
    11. Mensajes de Logs
    12. Créditos del código
    13. Parches
    14. Trac: Tareas, Bugs y características
      1. Tareas
    15. Acceso al repositorio de SVN
    16. Branches de Pyragua
    17. Relesases
    18. Internacionalización y Localización

Directrices de Desarrollo de Pyragua

Participando en el desarrollo de Pyragua

La página del semillero de desarrolo Pyrox es http://pyrox.utp.edu.co.

Listas de Correo

Documentación y Teoría

Agregar enlaces a la documentación generada por el semillero relacionada con Pyragua de alguna forma, y también a páginas extener

Licencia de Pyragua

Guía del código

Consejos para empezar a estudiar el código.

Estructura del repositorio

Directrices para el código fuente

Python utiliza la identaciones para determinar los bloques de código, por lo que el código de python es muy consistente. Para Pyragua utilizamos los siguientes estándares, que son muy parecidos a los recomendados para Python.

Para el desarrollo seguimos la siguiente guía de estilo. En esta página hay mucho más que una guía de estilo, también hay muchas recomendaciones para escribir código más pythonico. A continuación precisaremos algunos elementos que no se definen en esta guía, o que son solo recomendaciones.

Identación

Todo el código de Pyragua debe estar identado con espacios en blanco y usaremos siempre 4. Pyragua será configurable, pero por defecto usará esta esta configuración para el código.

Al momento de agrupar métodos relacionados se pueden utilizar dos lineas en blanco.

Nombres

Para atributos privados se recomienda el uso de nombres iniciados con '' (doble guión bajo).

Comentarios

Es muy importante actualizar los comentarios cuando se realicen cambios en el código. No se desea tener comentarios contradictorios.

Documentación

Las Docstrings son todas las cadenas que aparecen al principio de un móduolo, clase, función, o método. Esas cadenas se transforman en el atributo doc del objeto, y es la cadena que se imprime al ejecutar help(nombre_funcion_o_metodo_o_etc).

Por lo general todos los módulos, las clases, los paquetes, y los métodos públicos y funciones deben tener cadenas de documentación. Los paquetes se documentan en el archivo init.py del paquete.

Para la documentación de Pyragua se utilizará Epydoc por lo tanto parte de los estándares de documentación que se manejarán harán uso de la sintáxis de este. 

#-*- coding: utf-8 -*-

'''Cadena de documentación del módulo.'''

class MiClase:
    '''Esta es mi clase.'''

    def __init__(self):
        '''Documentación de un método público.'''

def func(a, b):
    '''Documentación de esta función.
    @param a: Descripción del parámetro a
    @type a: número
    
    @param b: Descripción de b
    @type b: cadena
    
    @raise exception: Descripción de las circunstancias en las cuales se levanta exception    

    @rtype: Retorna número o None
    @return: Descripción del valor retornado por 
    '''

Este tipo de documentación es reconocida por el interprete. Sin embargo, también hay otro tipo de cadenas de documentación que pueden utilizarse, y ques on reconocidas por aplicaciones externas para la creación de documentación. Las cadenas literales situadas después de una igualación de una variable, es la documentación de esa variable. 

g = 'module attribute (module-global variable)'
"""Est es la docstring de g."""

values = []
"""@ivar values: Documentación de values."""

class AClass:

    c = 'class attribute'
    """Esta es la docstring AClass.c's."""

    def __init__(self):
        """Method __init__'s docstring."""

        self.i = 'instance attribute'
        """Documentación de self.i's."""

def f(x):
    """Function f's docstring."""
    return x**2

f.a = 1
"""Documentación del atributo de función f.a."""

#: Descripcioń de la siguiente variable.
siguiente_variable = 1

en_linea = 0 #: Documentación en linea reconocida por Epydoc

def function(arg):
    """Esta es la docstring __doc__ de function."""
    """
    Esta es una docstring adicional, ignorada por el compilador de byte-code,
    pero extraída por utilidades de documentación.
    """
    pass

Excepciones

La captura de excepciones genéricas se debe evitar en la medida de lo posible. 

try:
  f = open("archivo.txt")
except:
  pass

Una captura de excepciones de esa forma no permite conocer con precisión qué error fue el que realmente ocurrió. Además, pocas veces se desea darle el mismo tratamiento a todas las excepciones. Debería por tanto especificarse en la clausula except, el nombre de la excepción que se quiere capturar, y las excepciones inesperadas no se deben capturar. 

try:
  f = open("archivo.txt")
except IOError:
  print "Error de entrada/salida"

Si el error es diferente a uno de entrada, se muestra un mensaje respectivo, y se pueden hacer más cosas al respecto. Además, si hay algún otro tipo de error, como por ejemplo, un error sintáctico en el código, no se ignora silenciosamente, ni se trata igual que un error de entrada salida.

Convenciones para los mensajes de error

Otras convenciones

El ChangeLog

Pyragua tiene en su directorio raíz un archivo llamado ChangeLog, donde los desarrolladores deben registrar los cambios relevantes realizados.

Los cambios relevantes son los relacionados con cambios en APIs (nombres de funciones y métodos), cambios en nombres de clases, cambio en nombres de archivos, o en los casos en que se elimina alguno, y otros cambios que se dejan a criterio del desarrollador, y que se considere importante anunciar (correcciones de bugs también).

Se hará uso del formato de ChangeLog definido por la GNU que se puede encontrar en http://www.gnu.org/software/emacs/manual/html_node/emacs/Format-of-ChangeLog.html. Como ejemplo del ChangeLog pueden mirar el ChangeLog actual de Pyragua http://pyragua.pyroxdev.org/browser/branches/pyragua0.2.5/ChangeLog.

Tests con PyUnit?

Escribiendo los tests antes de codigicar

Mensajes de Logs

Uso de logging.

Créditos del código

Parches

Trac: Tareas, Bugs y características

La herramienta para manejo de proyectos que utilizamos para Pyragua es Trac. La base de Trac son los tickets, y es la forma en que este maneja las tareas de un proyecto, los bugs y las características sugeridas por otras personas. La idea es manejar algunas cosas en común que se deben definir en cada ticket de cada tipo creado.

Tareas

Una tarea (task) corresponde a algo que se debe realizar en un milestone de un proyecto. Se deben tener las siguientes consideraciones al momento de crear un ticket correspondiente a una tarea:

Acceso al repositorio de SVN

Branches de Pyragua

Relesases

Internacionalización y Localización