PDF de programación - Manual de estilo - Python

Manualdeestilo
30deoctubrede2015

Losprogramassonejecutadospormáquinas,perohandeserleídosymantenidosporhumanos.
Esnecesario,portanto,escribirprogramasqueseanfácilesdeleeryenlosqueseasencilloentender
laestructuraylalógicadelmismo,esdecir,saberquéhaceycómolohace.
Acontinuacióndamosunaseriedepautasyconvencionesqueayudanalalegibilidadycom-
prensióndelosprogramas.Intentaremosseguirestasnormasentodoslosprogramasqueaparezcan
alolargodelaasignatura.
1. Nombresycomentarios
Porclaridad,paraaumentarlalegibilidadyevitarproblemasconcaracteresespeciales(como
acentos),losnombresdefuncionesyvariablesestaránescritoseninglés.
Losnombresdevariablesseránaclaratorios.Ejemplosdenombresclarosson: maximum, radius,
area, speed.Ejemplosdenombresconfusosson: a1, c, xxx.Lasvariablesíndiceusadaspara
recorrerbuclespuedentenernombressencillosysimilaresalosqueclásicamentesseutilizan
enmatemáticas: i, j, k.
Enmuchasocasiones,aldefinirconprecisiónunidentificadorparafuncionesovariablesuti-
lizamosvariaspalabras.Enestoscasos,laspalabrasquecomponenelidentificadorseunirán
conunguiónbajo.Porejemplo: min_distance, shortest_path, validate_data...
Todoeltextoqueaparezcaenelprogramaparaexplicarelmismo(comentarios,docstring,etc.),
tambiénestaráescritoeninglés.
2. Funciones
Todaslasfuncionesdebenestardocumentadaseninglésexplicandoquéhacen,quéargumentos
aceptanyquédevuelven.Estecomentario,queseconocecomodocstringdebecumplirelformato
quemuestralafigura1.
Esta forma de comentar es muy importante, pues las diferentes herramientas que utilicemos
para programar en python generan documentación a partir de la información contenida en
eldocstring.EnSpyder,porejemplo,ladocumentacióndelafunciónanteriorseveríacomo
apareceenlafigura2.
Dentrodelcuerpodelasfuncionesseusaránlosparámetrosdelafunciónovariableslocalmente
definidas,noseusaránvariablesglobales.
3. Espaciadoyseparación
Solohabráunainstrucciónporlínea
Seimportaránlosmódulosenlíneasseparadas.Porejemplo:

1

"""
Given two numbers a and b , return their average value .

Parameters
----------
a : number ( int or float )

Firsts number

b : number ( int or float )

The average value of a and b

Second number

1 def average (a , b ):
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

Returns
-------
float

Example
-------
>>> average (5 , 10)
7.5
"""
return (a + b) / 2.0

Figura1:Ejemplodedocstringparaunafunción

Figura2:EjemplodevisualizacióndeldocstringdeunafunciónenSpyder

2

1 import string
2 from PIL import Image
Laslineasdetextonopuedenocuparmásde80caracteres
Habrá2líneasenblancoparasepararfunciones
Como norma general, se dejará un espacio entre el operador y los operandos, incluido el
operadordeasignación.Ejemplos(elsímbolo ॷrepresentaunespacio):
1 pi ॷ=ॷ 3.14
2 area ॷ=ॷ side ॷ*ॷ side
Ejemplosdeexpresionesquenocumplenesteestiloson:
1 pi =3.14
2 pi ॷ =3.14
3 area ॷ=ॷ side * side
Enexpresionesmáscomplejas,esposiblequejuntaroperadoresyoperandos,deformauniforme
ycuidadosa,mejorelalegibilidad.Porejemplo,laexpresión
1 yॷ=ॷ(a*fॷ -ॷc*e )/( - c*bॷ+ॷa*d)
puedesermásfácildeleeryentenderque
1 yॷ=ॷ(aॷ*ॷfॷ -ॷcॷ*ॷe)ॷ/ॷ(-cॷ*ॷbॷ+ॷaॷ*ॷd)
Alinvocarodefinirfuncionesnosedejaráningúnespacioalladodelosparéntesis.Losargu-
mentossesepararánconunacomaseguidadeunespacio.Ejemplos:
1 def ॷ maximun (a ,ॷb ):
2 maximum (3 ,ॷ 45)
Ejemplosquenocumplenesteestiloson:
1 def ॷ maximun (a ,b ):
2 def ॷ maximun (ॷa ,bॷ ):
3 def ॷ maximun (ॷa ,ॷbॷ ):
4 maximum (3 ,45)
5 maximum (ॷ 3 ,45)
6 maximum (ॷ3,ॷ 45 ॷ)
7 maximum (ॷ 3 ,45 ॷ)

3