OpenERP: El ERP de software libre

Buenas…

Os posteo aquí una guía de estilo traducida que ha publicado Sharoon Tomas en su blog aquí. Por favor, todos los comentarios, mejoras y sugerencias que se os ocurran, posteadlas directamente en el post origial de Sharoon para que no se pierda niguna y se vaya completando la guía:

My first proposals for framework team (Updated with community feedback)

Mi primera proposición para el grupo Framework (actualizado con la opinión de la comunidad)

A. Strict PEP style guide compliance (http://www.python.org/dev/peps/pep-0008/)

* El código se lee mucho más a menudo de lo que se escribe. Por lo que debemos poner el foco en su legibilidad

• Indentación: Usa espacios. No tabuladores. Cada indentación deben ser cuatro espacios.
• Líneas en blanco: Las definiciones de métodos dentro de una clase deben ser separadas por una línea en blanco.
• Separación de código y longitud de línea: La longitud de línea debe ser menos de 80 caracteres (=79) . En el contexto de Open ERP separa las tuplas de los campos de selección en varias líneas. (esto también ayuda con el control de versiones)
• Importación: Las sentencias de importación (imports) deben estar en líneas separadas. Los imports siempre deben estar al principio del archivo, justo después de cualquier comentario de módulos y strings de documentación y antes de las constantes y variables globales del módulo. Los imports deben estar agrupados en el siguiente orden.

1. imports librerías standar(time, datetime, os etc)
2. imports de librerías adicionales relacionadas (mako, relatario etc)
3. imports específicos y librerías locales (osv, fields, external_osv etc)

• Los comentarios que contradicen el código son peor que el que no haya comentarios. Siempre prioriza la actualización de comentarios cuando cambie el código.
• Los comentarios deberían ser sentencias completas. Si un comentario es una frase o sentencia, su primera palabra debería ser capitalizada, a menos que sea un identificador que se inicia con minúsculas (nunca alterar la forma de los identificadores )

Para los strings de documentación deberíamos seguir esto http://www.python.org/dev/peps/pep-0257/

• Guion bajo: _single_leading_underscore: Para métodos on_change, métodos o campos de función, métodos para asignar campos de selección y métodos en botones de vistas. También para métodos que no deberían ser llamados directamente. (Indicador de uso interno.  p.e. “from M import *” no importa objetos cuyo nombre comienza por guión bajo)
• Guión bajo al final: – single_trailing_underscore_: usado por convención para evitar conflictos con palabras reservadas de python. Eg: Tkinter.Toplevel(master, class_=’ClassName’)
• Doble guion al principio: – __double_leading_underscore: al nombrar un atributo de clase, invoca al nombre del “padre”  (dentro de la clase class FooBar, __boo se convierte en _FooBar__boo; ver abajo).
• Guion doble al principio y al final: __double_leading_and_trailing_underscore__: objetos “magic” objetos o atributos que viven en espacios de nombres controlados por el usuario E.g.           __init__,  __import__ or __file__.  Nunca te inventes estos nombres. Solo utilizalos como se ha documentado.
• Nombres de módulos de Open ERP: Los módulos deben ser cortos, en minúsculas. Los guiones puden ser utilizados en el nombre del módulo si aporta legibilidad.
• Versiones de módulos de Open ERP : <<Por favor, alguien que lo sepa que lo explique>>
• Nombres de excepción: Porque las excepciones deberían ser clases. Las convenciones de nombrar las clases aplican aquí. De todas formas, deberíais usar el sufijo “Error” en vuestros nombres de la excepción (si la excepción, es un error)

Nota: Open ERP tiene mucho de esto: Line 880 in orm.py : raise _(‘The read method is not implemented on this object !’) está mal. devuelve un string al método por _ in tools.translate return string. Las excepciones string están prohibidas en en py 2.6 and posteriores.
Al enviar una excepción, usar “raise osv_except(name,value,exception_type)” en vez de la antigua forma “raise ValueError, ‘message’”

• Los nombres de funciones deberían ser minúsculas, con palabras separadas por guiones si fuese necesario para mejorar la legibilidad.
• Constantes: Son declaradas a nivel de modulo y escritas en mayúsculas con guiones separando palabras. Ejemplos include MAX_OVERFLOW y TOTAL.
• Diseño para herencia: Decide si los atributos de clase deben ser públicos o no. Si no estás seguro márcalos como no públicos con guiones al principio. En Open ERP a los métodos de contexto los puedes llamar por self.pool.get(‘xyz’).method no deberían tener guiones al principio. Eg. method en un campo función puede ser una función no pública _get_prod_price y llamar a una función pública get_price
• El código debería ser escrito de una forma que no ponga en desventaja otras implementaciones de python. Eg. Evita usar mx datetime (ha estado retrasando el proyecto  oo_jython project por bastante tiempo. ) Teneis una lista de lo qeu debemos usar y lo que no? –C. Simonis . Creo que la comunidad necesita proponer módulos que ellos saben que no funcionan con jython etc. — Sharoon
• Comparaciones con tonos simples como None deberían hacerse siempre con ‘is’ o ‘is not’, nunca con operadores igual. Por lo que if x==None está mal, usa x is None

B) codificación xml

* escribe commentarios !!!

* Difice los módulos complejos en varios archivos xml

* usar  xmllint – solo una pregunta – IMHO 2 es mejor que 4 por legibilidad.

–formateo

Reformatear and reindentar la salida. La variable de entorno XMLLINT_INDENT controla la indentación. El valor por defecto son 2 espacios “  “).

* structure (1. try)

** tree

** form

** graph

** calendar

* menu

* action

Comunidad: Por favor, añadir/modificar/sugerir más convenciones
Referencia:

Python Style Guide essay: GVR: http://wiki.laptop.org/go/Python_Style_Guide

PEP8