Tabla de Contenidos
Guía de estilos de código
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.
Estilo general
Indentanción
4 espacios reales, no tabulador, sin excepción.
Longitud máxima de linea
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.
Continuación de expresiones largas
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' ]
Líneas en blanco
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'
Declaraciones y expresiones
Reglas generales de espacios en blanco
- 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']
Declaraciones Yoda, no son
Nunca compare constantes con variables, siempre variable con constante.
Bien:
if method == 'md5': pass
Mal:
if 'md5' == method: pass
Comparaciones
- 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.
Convención de nombres
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.
Argumentos de funciones y métodos
- 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).
Docstrings
Convenciones de Docstrings
- 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
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.
Comentarios
- 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)