python: les bonnes pratiques¶
fichier¶
#! /bin/python
# -*- coding: utf-8 -*-
#
# title of file
#
# explication
__author__ = "Rob Knight, Gavin Huttley, and Peter Maxwell"
__copyright__ = "Copyright 2007, The Cogent Project"
__credits__ = ["Rob Knight", "Peter Maxwell", "Gavin Huttley",
"Matthew Wakefield"]
__license__ = "GPL"
__version__ = "1.0.1"
__maintainer__ = "Rob Knight"
__email__ = "rob@spot.colorado.edu"
__status__ = "Production"
class NumberList(list):
"""comment class"""
def __init__(self, data, Name='', Alphabet=None):
"""Returns new Sequence object with specified data, Name, Alphabet.
data: The sequence data. Should be a sequence of characters.
Name: Arbitrary label for the sequence. Should be string-like.
Alphabet: Set of allowed characters. Should support 'for x in y'
syntax. None by default.
Note: if Alphabet is None, performs no validation.
"""
class FrequencyDistribution(dict):
pass #much code deleted
if __name__ == '__main__':
pass
Whitespace 1¶
- 4 espaces par niveau d’indentation.
- Pas de tabs.
- 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
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()
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”.
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.
Readme¶
Project
-------
psync -- synchronisation between src and dst
Prerequisites:
* Python 2.7 or higher.
Installation
------------
1. unzip source
2. python pysync.py
Authors
-------
Aoustin Frederic
License
-------
GPL3, see http://www.gnu.org/licenses/
Relase history
--------------
1.0 the first release
Utilisation
-----------
Zen¶
Python est basé sur uen philosophie
import this
The Zen of Python, by Tim Peters
Beautiful is better than ugly.
Explicit is better than implicit.
Simple is better than complex.
Complex is better than complicated.
Flat is better than nested.
Sparse is better than dense.
Readability counts.
Special cases aren't special enough to break the rules.
Although practicality beats purity.
Errors should never pass silently.
Unless explicitly silenced.
In the face of ambiguity, refuse the temptation to guess.
There should be one-- and preferably only one --obvious way to do it.
Although that way may not be obvious at first unless you're Dutch.
Now is better than never.
Although never is often better than *right* now.
If the implementation is hard to explain, it's a bad idea.
If the implementation is easy to explain, it may be a good idea.
Namespaces are one honking great idea -- let's do more of those!
en français
La beauté vaut mieux que la laideur
L'explicite vaut mieux que l'implicite
Préfère le simple au complexe
Et le complexe au compliqué.
Mieux vaut le plat que l'imbriqué.
Mieux vaut l'aérien que le dense.
La lisibilité compte.
Les cas particuliers ne le sont pas assez pour violer les règles
Bien que le sens pratique l'emporte sur la pureté.
Les erreurs ne devraient jamais être silencieuses
A moins d'être explicitement réduites au silence.
Face à une ambiguïté, refuse la tentation de deviner.
Il devrait y avoir une-- et si possible une seule --façon évidente de
faire les choses.
Même si cette façon peut ne pas apparaître immédiatement évidente si
vous n'êtes pas hollandais.
Mieux vaut maintenant que jamais,
Quoi que jamais vaille souvent mieux qu'immédiatement là tout suite.
Si l'implémentation s'explique difficilement, c'est une mauvaise idée.
Si l'implémentation s'explique aisément, c'est peut-être une bonne idée.
Les espaces de nommage sont une sacré bonne idée -- Faisons plus de
trucs comme ça !