Guía de estilo para Python

readme.md

Guía de estilo para Python

Pequeña guía de estilo para código Python

1. Objetivo y descripción
2. Indentación y espaciado
3. Imports
4. Comments
5. Convenciones de nombrado
6. Créditos y autor

Indentación y espaciado

En Python el uso de una correcta indentación es forzoso dado que es el delimitador para el intérprete de las sentencias de bloque, sin embargo no existe una norma en cuanto al número de espacios o tabs por nivel de indentación.

Usar 4 espacios por nivel de indentación.

# Correcto
def hola():
    print "Bien"

# Incorrecto
def hola():
	print "Mal"

Por legibilidad del código las líneas debe ser limitadas a un máximo de 79 caracteres, en caso de tener una sentencia que supere esta cantidad de caracteres su espacio deberá ser así:

with open('/path/to/some/file/you/want/to/read') as file_1, \
     open('/path/to/some/file/being/written', 'w') as file_2:
    file_2.write(file_1.read())

La separación entre métodos de una clase debe ser hecha por una sola línea en blanco, mientras que la separación entre la última línea de una clase y la primera de la siguiente debe ser de dos líneas.

class CuentaFacebook(models.Model):
    token = models.CharField(max_length=255)
    movil = models.ForeignKey(Movil)


class EventoCorreo(models.Model):
    cuenta = models.ForeignKey(CuentaCorreo)

Imports

Los import deben encontrarse separados por líneas, evitando importar varios paquetes, módulos o clases en una sola sentencia.

import os
import sys

Los import siempre deben ubicarse en las primeras líneas del archivo, justo después de la codificación del archivo, comentarios y documentación y antes de constantes y variables globales del módulo.

Los import deben ser agrupados en el orden:

1. Librerías estándar
2. Librerías del módulo o aplicación
3. Librerías locales

Se debe evitar bajo cualquier circunstancia el uso de wildcard imports (*).

# Correcto
import hmac
import uuid

from django.core.validators import EMPTY_VALUES
from django.utils.timezone import now
from enum import unique, IntEnum
from django.db import models

# Incorrecto
from django.core.validators import *
from django.utils.timezone import *
import enum
from django.db import models
import hmac
import uuid

Comments

Los comentarios son extensiones del código que ayudan a clarificar el objetivo del mismo, sin embargo tener malos comentarios es peor aún que no tener.

Para que un comentario sea considerado válido debe contemplar:

1. Los comentarios son sentencias, es decir su primera palabra deberá estar capitalizada a menos de que sea un identificador.

2. Los comentarios inline, es decir escritos sobre la misma línea que la sentencia deben ser separados por al menos dos espacios de esta y deben comenzar con #.

3. Los comentarios no deben ser utilizados para explicar cosas obvias dentro del código sino funcionalidad que por su naturaleza propio no es tan sencillo entender en primera instancia.

Docstrings.

Se le conoce a los buenas cadenas de documentación como docstrings.

Todos los módulos públicos en un desarrollo en Pythom así como las funciones, clases y métodos deben tener un docstring. La convención para escribir estos es:

Escribir 3 comillas dobles antes de empezar la cadena y terminarla con los mismos caracteres.

"""Return a foobang

Optional plotz says to frobnicate the bizbaz first.
"""

Convenciones de nombrado

Existe una gran cantidad de convenciones de nombrado dentro del lenguaje Python, sin embargo cada una de ellas está asociada a nombar un tipo de objeto en específico.

_single_leading_underscore

Es utilizado para nombrar elementos de módulos que no serán expuestos por medio de un wildcard import.

single_trailing_underscore_

Es utilizada para evitar conflictos con el uso de palabras reservadas de Python, por ejemplo:

Es utilizada para evitar conflictos con el uso de palabras reservadas de Python

Los módulos deben tener nombres cortos y en minúsculas todos sus caracteres, pueden ser usados guiones bajos si eso mejora la legibilidad el nombre.

Los paquetes deben seguir la mimsa convención que los módulos sin embargo el uso de los guiones bajo no se recomienda.

Las clases escritas en Python deben seguir la notación CapWords para su nombrado. Existen algunas clases que cumplen funciones específicas dentro del lenguaje, como las excepciones, estas, por legibilidad deberán tener el sufijo Error.

El nombre de métodos o funciones debe hacerse en minúsculas con palabras separadas por guiones bajos para mejorar la legibilidad.

Por último, las constantes deben ser escritas en mayúsculas separadas por guiones bajos para mejorar la legibilidad.

Referencias

• Referencia 1:
  • PEP 8 - Style Guide
• Referencia 2:
  • Google Python Style Guide

Créditos y autor

• Autor del snippet: Israel Gómez @imarban
• Los snippets pertenecen a KamikazeLab