Tutoriel Style de programmation - COURS N°2

[fred]

Bonjour,

À savoir : Ce tutoriel risque d'être modifié, changé de place, voir même supprimé selon les décisions de l'équipe hackademics. Sa présence, est dû aux attentes des membres du forum participant au cours Python.

Tout conseils, modifications à votre demande, sera envoyé par MP.

STYLE PROGRAMMING

Dans ce cours, il est très important que l'on soit d'accord sur le style utilisé par tous les codeurs python dignes de ce nom.

Être strict au début, s'imposer une discipline, rendra votre apprentissage en langage python simplifié par la suite, car vous n'aurez pas de difficultés à lire les tutoriels sur le web.

Pour cela un plan s'impose

1. Les commentaires
2. La documentation
3. L'indentation
4. Choix des noms

I) LES COMMENTAIRES

Pourquoi sont-ils utiles? On est pas dans votre tête, des centaines de solutions sont possibles, quelles est celle choisie dans la résolution de votre problème? Les commentaires aideront les lecteurs à comprendre où vous souhaitiez en venir, quel algorithme a été choisi par vos soins.

Ne commentez pas ce qui est évident, c'est inutile d'écrire des pavés de commentaires.

Les commentaires s'expriment par le caractère dièse # suivi du commentaire.

Exemple : print(nom) # Affichage du nom utilisateur

II) LA DOCUMENTATION

On a la possibilité en python de récupérer dynamiquement la documentation à l'aide de l'attribut __doc__

Exemple : print("12".__doc__) # affichera la documentation sur le type string (chaîne de caractères)

Résultat :

>>> print("12".__doc__)
str(object[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or
errors is specified, then the object must expose a data buffer
that will be decoded using the given encoding and error handler.
Otherwise, returns the result of object.__str__() (if defined)
or repr(object).
encoding defaults to sys.getdefaultencoding().
errors defaults to 'strict'.

Vous souhaitez vous renseigner sur la documentation d'une fonction, d'une méthode ou autres, la commande help(fonction) sera votre amie.

Exemple : help("12".upper)

Help on built-in function upper:

upper(...)
    S.upper() -> str
    
    Return a copy of S converted to uppercase.

III) L'INDENTATION

C'est un point sensible pour tous les codeurs python, l'indentation est une marque de fabrique du langage, elle représente la lisibilité de votre code (oui carrément).

L'indentation représente la taille de l'espacement entre chaque bloc créé.

Exemple :

chaine = input("Entrer votre chaine : ")
if chaine :
    print(chaine)

On remarque qu'un bloc débute après le caractère ":", puis vient l'indentation d'une taille de 4 espaces.

Plusieurs solutions d'indentation possibles

1 à 2 espaces : Taille insuffisante, on remarque très mal à quel bloc de code appartient l'instruction

8 à 10 espaces : Taille trop importante, si il y a beaucoup de niveaux d'indentation, la ligne sera repliée à la ligne suivante, du coup la lisibilité devient difficile

4 espaces : 99% des codeurs python l'utilise, cette indentation est représentée dans le guide (PEP8) comme conseillée

IV) LE CHOIX DES NOMS

Choisir le nom de ses variables, de ses classes, modules, ... est un choix qui ne doit pas être pris à la légère, il représente votre compréhension d'un problème donné, mais aussi la possibilité au lecteur de comprendre que représente concrètement vos entrées dans le programme.

Exemple d'erreur fréquente : age = int(input("Entrez votre année de naissance : "))

On remarque la variable age n'est pas cohérente par rapport à la demande de donnée utilisateur. En effet on demande une année et non un age, voyez-vous?

Pour rester dans le contexte d'un guide de style, ce cours n'aura pas d'exercices.

Bonne journée,

[DreAmuS]

Merci pour ce tutoriel.

Sympa la commande help().

Je ne sais pas si tu en parle quelques part, dans tes cours, mais une aparté sur les différents types d'erreurs seraient un plus.

Debug :erreurs de syntaxe, erreurs sémantiques et erreurs à l'exécution.

[_42_]

Concernant l'indentation, il est intéressant d'inclure dans l'entête du fichier, le code suivant :

#!/usr/bin/env python
# -*- Mode: Python; coding: utf-8; indent-tabs-mode: nil; tab-width: 4 -*-

En effet, cela contraindra le logiciel utilisateur, à transformer la tabulation en 4 espaces ... n'est-ce pas ?!
Cela permet aussi de respecter, plus facilement, PEP8, à cet égard ;-)

[_42_]

(Rahhh, c'est casse-pied que l'on ne puisse pas rééditer ses propres messages)

À-propos des commentaires, tu as aussi les commentaires de fonctions, méthodes, et classes qui sont recommandées par le PEP8 - si je ne me trompe pas - et qui, à juste titre sert aux informations de documentations ... et qui eux, sont encadrés par un triple quote '''.

Si comme tu le dis, il ne faut pas mettre des tonnes de commentaires, la recommandation PEP nécessite de les décrire !

[fred]

Bonsoir,

Je donne les cours sur python version 3.x, l'encodage par défaut est l'UTF8, il est donc inutile de spécifier l'encodage.

En ce qui concerne la ligne

#!/usr/bin/env python

C'est une spécificité Unix, et n'a pas sa place sous un environnement Microsoft. Et comme le gros avantage de Python est sa portabilité...