samedi 2 août 2014

Conventions de nom en Python

Vous voulez savoir quels sont les conventions pour nommer des fonctions, des variables, des classes en Python?

Je vous propose la lecture de:
Une ressource vraiment importante et fiable issue des PEPs (Python Enhancement Proposal).

Nom des packages (paquets) et des modules
Les nom des modules doivent être court et uniquement en minuscule. Vous pouvez utiliser des soulignés (underscores) dans les noms des modules si cela améliore la lisibilité. Les packages (paquets) Python doivent également être court et uniquement minuscule. L'utilisation de souligné (underscore) est déconseillé dans le nom des paquets.

Etant donné que le nom du module correspond à un fichier sur le système d'exploitation -- et que certain système d'exploitation sont sensible à la case (ou tronque les noms) -- il est important de choisir un nom de module aussi court que possible.  Cela n'est pas un problème pour des systèmes Unix/Linux mais pourrait le devenir si vous portez votre code vers de vieux Mac, Windows, Dos.

Lorsqu'un module d'extension écrit en C ou C++ est accompagné d'un module Python offrant une interface d'accès de haut niveau (ex: via une interface orienté objet), ALORS le module C/C++ dispose d'un souligné (underscore) en entête (ex: _socket).

Nom des classes

Les noms de classes devrait utiliser la convention de noms des mots capitalisés (VoiciUnExempleDeNomDeClasseEnCapitalizedWord).

La convention de nom des fonctions devrait être utilisé dans les cas d'une interface documentée pour être utilisée comme "callable".

Nom des exceptions
La convention de nom des classes est utilisé pour les exceptions car une exception est aussi une classe.
Le sufixe Error doit être utilisé dans le nom de vos exception (pour distinguer les exceptions des classes... si l'exception est, bien entendu, une erreur).


Nom des variables globales
(en supposant que les variables sont destinées uniquement à l'usage interne du module.) La convention à utiliser est similaire à celle des fonctions.

Pour les modules qui sont conçu pour utiliser via from M import * devraient utiliser le mécanisme __all__ pour éviter l'exportation des variables globales ou utiliser une ancienne convention qui consiste à préfixer de telles variables globales à l'aide d'un souligné (underscore, ce qui permet d'indiquer que ces variables globales ne sont pas publique au niveau du module (hors du module).
 
Nom des Fonctions
Les noms de fonction devraient être en minuscule, avec des soulignés (_) insérés pour améliorer la lisibilité (en fonction des besoins).

L'utilisation du "mixedCase" est toléré si c'est un style déjà prédominant  (ex. threading.py), ce qui permet de préserver la retro-compatibilité.

Les arguments des fonctions et des méthodes
Toujours utiliser self comme premier argument d'une méthode.

Toujours utiliser cls pour le premier argument d'une méthode de classe.

Nom des méthodes et variables d'instance
Use Utiliser la convention de nom des fonctions:Les noms de fonction devraient être en minuscule, avec des soulignés (_) insérés pour améliorer la lisibilité (en fonction des besoins).

Utiliser un souligné (underscore) pour débuter le nomdes des méthodes non publique et les variables d'instance.

Pour éviter une colision de nom avec les sous-classes, il est possible de préfixer le nom avec un double souligné (underscore) pour forcer Python à limiter la portée du nom.

Lorsque vous avez un double souligné (underscore), en interne, Python préfixe ce nom ave le nom de la classe. Si la classe Foo à un attribut nommé __a, cet attribut ne peut pas être accessible via Foo.__a. (Un utilisateur insistant devrait utiliser Foo._Foo__a.)
En général, le double souligné devrait être utilisé pour éviter un conflit de nom avec un attribut d'une classe destinée à être une sous-classe.

Note: il y a quelques contreverses concernant l'usage des __noms.

Constantes
Les constantes sont généralement définit au niveau du module, écrit avec des lettres capitales et utilisant des soulignés (underscore) pour séparer les mots. Exemples: MAX_OVERFLOW et TOTAL.