Style du code

La lisibilité est importante

Les programmes doivent être écrits pour être lus par des gens et accidentellement exécutés par les machines.

-- Abelson & Sussman, Structure and Interpretation of Computer Programs

Essayez de rendre vos programmes faciles à lire et évidents.

PEP 8 : Style Guide pour le code Python

Une lecture immanquable : http://www.python.org/dev/peps/pep-0008/ (PEP = Python Enhancement Proposal)

Un PEP est une document procurant des informations à la communauté Python, ou décrivant une nouvelle fonctionnalité de Python et ses processus ou de son environnement.

La communauté Python a ses propres standards sur ce à quoi doit ressembler le code, codifiés dans le PEP8. Ces standards sont différents de ceux des autres communautés, comme C, Java, etc.

L'indentation et les espaces étant si importants en Python, ce Style Guide est une standard. Il est important que vous adhériez au guide ! La plupart des projets suivent ces conventions.

Whitespace 1

• 4 espaces par niveau d'indentation.
• Pas de tabs.
• Ne jamais mixer des tabs et des espaces.
• Un saut de ligne entre les fonctions.
• Deux sauts de ligne entre les classes.

Whitespace 2

• Ajoutez un espace après ", ", dans les dictionnaires, les listes, les tuples, les arguments d'une liste d'arguments et après ":" dans les dictionnaires mais pas avant.
• Mettez des espaces autour des assignements et des comparaisons (excepté pour les arguments d'une liste).
• Pas d'espace aux ouvertures/fermetures de parenthèses ou juste avant une liste d'arguments.

• Pas d'espace en ouverture/fermeture de docstrings.

  def make_squares(key, value=0):
      """Return a dictionary and a list..."""
      d = {key: value}
      l = [key, value]
      return d, l
  

Nommage

• joined_lower pour les fonctions, méthodes et attributs
• joined_lower ou ALL_CAPS pour les constantes
• StudlyCaps pour les classes
• camelCase seulement pour suivre des conventions pré-existantes
• Attributs: interface, _internal, __private

Mais essayez d'éviter la forme __privée. Je ne l'utilise jamais. Faites moi confiance. Si vous l'utilisez, vous le regretterez plus tard.

Longues lignes et continuité

Garder une taille de ligne inférieure à 80 caractères.

Utilisez la continuité implicite des lignes au sein des parenthèses/crochets/accolades :

def __init__(self, first, second, third,
             fourth, fifth, sixth):
    output = (first + second + third
              + fourth + fifth + sixth)

Utilisez les backslashs en dernier recours :

VeryLong.left_hand_side \
    = even_longer.right_hand_side()

Les backslashs sont locaux, ils doivent terminer la ligne sur laquelle ils sont. Si vous ajoutez un espace après le backslash, ça ne sert à rien. Ah aussi, c'est laid.

Longues chaînes de caractères

Les chaînes de caractères adjacentes sont concaténées par le parser:

>>> print 'o' 'n' "e"
one

Les espaces entre les chaînes ne sont pas requis, mais aident à la lisibilité. Tous les types de quotes sont utilisable :

>>> print 't' r'\/\/' """o"""
t\/\/o

La chaîne précédée par "r" est une chaîne de type "raw". Les backslashs ne sont pas évalués comme étant des caractères d'échappement dans les chaînes de type raw. Elles sont utiles pour les expressions régulières et les chemins de fichiers Windows.

Notez que les chaînes de caractères nommées ne sont pas concaténées :

>>> a = 'three'
>>> b = 'four'
>>> a b
  File "<stdin>", line 1
    a b
      ^
SyntaxError: invalid syntax

Cela vient du fait que la concaténation automatique est une fonctionnalité du parser/compiler Python, pas de l'interpréteur. Vous devez utiliser le signe "+" pour concaténer des chaînes de caractères à l'éxecution.

text = ('Long strings can be made up '
        'of several shorter strings.')

Les parenthèses autorisent la continuité implicite des lignes. Les chaînes de caractères sur plusieurs lignes utilisent les triple quotes :

"""Triple
double
quotes"""

'''\
Triple
single
quotes\
'''

Dans le dernier exemple ci-dessus (simple triple quotes), notez l'utilisation du backslash pour échapper les nouvelles lignes. Cela élimine les nouvelles lignes en conservant les quotes joliment alignées à gauche. Les backslashs doivent être à la fin de leurs lignes.

Déclarations

Bon :

if foo == 'blah':
    do_something()
do_one()
do_two()
do_three()

Mauvais :

if foo == 'blah': do_something()
do_one(); do_two(); do_three()

Les espaces et l'indentation sont de bons indicateurs visuels du flot du programme. L'indentation de la seconde ligne du "Bon" ci-dessus montre au lecteur que quelque chose va se produire, alors que le manque d'indentation dans le "Mauvais" exemple cache le "if".

Les déclarations multiples sur une même ligne sont une torture. En Python, la lisibilité compte.

Docstrings et Commentaires

Docstrings = Comment utiliser le code

Commentaires = Pourquoi (rationnel) et comment le code fonctionne

Les docstrings expliquent comment utiliser le code et sont là pour les utilisateurs de votre code. Quelques usages :

• Expliquer le but d'une fonction même si ça vous semble évident car ça ne semblera pas forcément évident à une personne plus tard.
• Décrire les paramètres attendus, les valeurs retournées et les exceptions levées.
• Si la méthode est fortement couplée à un seul appelant, mentionner la fonction appelante (attention au fait que celle-ci puisse changer).

Les commentaires expliquent pourquoi et sont pour les mainteneurs de votre code. Examples incluant des notes pour vous-même, comme :

# !!! BUG: ...

# !!! FIX: This is a hack

# ??? Why is this here?

Les deux types sont de votre ressort donc écrivez de bonnes docstrings et de bons commentaires !

Les docstrings sont utiles pour un usage interactif (help()) et pour les systèmes d'auto-documentation.

Les commentaires et docstrings faux sont pire que tout. Donc conservez les à jour ! Lorsque vous effectuez des modifications, assurez vous que les commentaires et les docstrings sont cohérents avec le code.

Il y a un PEP entier consacré aux docstrings, PEP 257, "Docstring Conventions".

La pratique a raison de la théorie

Il y a toujours des exceptions. Issu du PEP 8 :

Mais plus important : sachez être pertinents - parfois le style guide ne s'applique pas. Lorsque vous avez un doute, utilisez votre raison. Étudiez d'autres possibilités et décidez de ce qui vous semble le mieux. Et n'hésitez pas à demander ! Deux bonnes raisons de ne pas suivre une règle particulière :

(1) Lorsque appliquer la règle va rendre le code moins lisible, même pour quelqu'un qui est habitué à lire du code qui suit les règles.

(2) Pour être cohérent avec du code préexistant qui enfreint aussi ces règles (peut-être pour des raisons historiques) -- même si c'est aussi une opportunité pour faire un peu de nettoyage (dans un pur style XP).

... mais la pratique ne doit pas réduire la théorie à néant !

On plonge maintenant au cœur du tutoriel : les astuces. On va commencer avec les plus faciles et augmenter progressivement le niveau.