ArgoGpl / Orfeo

SIIM2 está escrito en Python 2.7 , la guía de codificación está inspirada en PEP8 y en la guía de codificación de PoCoo .

Para solución de conflictos, primero referirse al documento presente, si no hay información suficiente referirse a la guía de PoCoo, y finalmente a la guía PEP8.

4 espacios reales, no tabulador, sin excepción.

79 caracteres con un límite suave de 84 caracteres si es absolutamente necesario. Trata de evitar código anidado muy profundo usando inteligentemente las instrucciones break, continue y return.

Para continuar una expresión se puede usar backslash, en cuyo caso se debe alinear la siguiente línea al último punto o signo igual o identado a cuatro espacios:

    this_is_a_very_long(function_call, 'with many parameters') \
        .that_returns_an_object_with_an_attribute
 
    MyModel.query.filter(MyModel.scalar > 120) \
                 .order_by(MyModel.name.desc()) \
                 .limit(10)

Si rompe una expresión con paréntesis o llaves, alinee a las llaves:

    this_is_a_very_long(function_call, 'with many parameters',
                        23, 42, 'and even more')

Para listas o tuplas con muchos elementos, pare inmediatamente después de abrir llaves:

    items = [
        'this is the first', 'set of items', 'with more items',
        'to come in this line', 'like this'
    ]

Funciones de alto nivel y clases son separadas por dos líneas en blanco, todo lo demás por una. No use muchas líneas en blanco para separar segmentos lógicos en código. Ejemplo:

    def hello(name):
        print 'Hello %s!' % name
_n
 
    def goodbye(name):
        print 'See you %s.' % name
 
 
    class MyClass(object):
        """This is a simple docstring."""
 
        def __init__(self, name):
            self.name = name
 
        def getAnnoyingName(self):
            return self.name.upper() + '!!!!111'

• No espacios en blanco para operados unitarios que no son palabras (e.j. -, ~ etc.) así mismo como en los lados internos de los paréntesis.
• Espacio en blanco separa operadores binarios

Bien:

    exp = -1.05
    value = (item_value / item_count) * offset / exp
    value = my_list[index]
    value = my_dict['key']

Mal:

    exp = - 1.05
    value = ( item_value / item_count ) * offset / exp
    value = (item_value/item_count)*offset/exp
    value=( item_value/item_count ) * offset/exp
    value = my_list[ index ]
    value = my_dict ['key']

Nunca compare constantes con variables, siempre variable con constante.

Bien:

    if method == 'md5':
        pass

Mal:

    if 'md5' == method:
        pass

• Entre tipos arbirarios: == and !=

Contra singletons con is y is not (ej: foo is not None) Nunca compare algo con True o False (por ejemplo nunca haga foo == False, haga not foo encambio)

• Pruebas negadas de contenido:

Use foo not in bar en vez de not foo in bar.

• Pruebas de instacia:

isinstance(a, C) en vez de type(A) is C, pero tratando de evitar pruebas de instancia en general.

Todos los nombres de variables, clases, métodos y funciones, comentarios deberá estar en inglés. La documentación deberá estar en inglés y español

• Nombres de clases: CamelCase, con acronimos en mayúsculas (HTTPWriter y no HttpWriter).
• Nombres de variables: minúsculas_con_raya_al_piso.
• Métodos y funciones: camelCaseConMinusculaInicial.
• Constantes: MAYÚSCULAS_CON_GUIN_BAJO.
• Expresiones regulares precompiladas: nombre_re.

Miembros protegidos son prefijados con un guión bajo _. Doble guión bajo __ son reservados para clases mixin.

En las clases con palabras claves, guiones bajos precedentes son añadidos. Clases con builtins son permitidas y no deben ser resuletas agregando un guión bajo al nombre de la variable. Si la función necesita acceso a una buildin oculta, rebind el buildin a un nombre diferente en cambio.

• Métodos de clase: cls como primer parámetro.
• Métodos de instancia: self como primer parámetro.
• Lambdas para propiedades pueden tener el primer parámetro reemplazado con x, como en display_name = property(lambda x: x.real_name or x.username).

• Todas las docstrings estan formateadas usando reStructuredText como son entendidas por Sphinx. Dependiendo del número de lineas en el docstring son organizadas de manera diferente. Si es sólo una línea, se debe cerrar la triple comillas en la misma línea, en caso contrario las triple comillas que abren y el texto van en la misma línea, y las triple comillas que cierran tien su propia línea.

    def foo():
        """This is a simple docstring."""
 
 
    def bar():
        """This is a longer docstring with so much information in there
        that it spans three lines.  In this case, the closing triple quote
        is on its own line.
        """

• En general, los docstrings deben ser partidos en ,cortos (mejor sólo una línea) resúmenes e información detallada, si es necesario, después de una línea vacía.

Encabezado del módulo consiste en una declaración del encoding utf-8 y el docstring estándar:

header.py

    # -*- coding: utf-8 -*-
    """
        paquete.modulo
        ~~~~~~~~~~~~~~
 
        Acá viene una descripción cortá del módulo.
 
        :author: Nombre Apellido <correo@dominio.tld>
        :author: Otros Autores <correo2@dominio.tld>
        :copyright: (c) 2013 por Fundación CorreLibre
        :license:  GNU AFFERO GENERAL PUBLIC LICENSE
 
    SIIM2 Storage is the base of SIIM2's Framework
    Copyright (C) 2013  Fundación CorreLibre
    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU Affero General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.
 
    This program 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 Affero General Public License for more details.
 
    You should have received a copy of the GNU Affero General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.
    """

Por favor tener en cuenta los derechos reservados y licencias requeridas por el proyecto SIIM2.

• Las reglas para los comentarios con similares a las reglas para docstrings, ambos son formateados en reStructuredText. Si algun comentario es usado para documenta un atribulo, poner dos puntos después del simbolo (#):

class User(object):
    #: the name of the user as unicode string
    name = Column(String)
    #: the sha1 hash of the password + inline salt
    pw_hash = Column(String)