python: les bonnes pratiques **************************** fichier ======= .. code-block:: python #! /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. .. code-block:: python 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 : .. code-block:: python def __init__(self, first, second, third, fourth, fifth, sixth): output = (first + second + third + fourth + fifth + sixth) Utilisez les backslashs en dernier recours : .. code-block:: python VeryLong.left_hand_side \ = even_longer.right_hand_side() Déclarations ============ Bon : .. code-block:: python if foo == 'blah': do_something() do_one() do_two() do_three() Mauvais : .. code-block:: python 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 ====== .. code-block:: bash 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 .. code-block:: python 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 .. code-block:: bash 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 !