Conventions syntaxiques

introduction

Cette page à pour vocation de rassembler les différentes règles de rédaction du programme ESM. Étant donnée le nombre important de collaborateurs attendu pour l'élaboration de ce programme il convient de s'accorder au préalable sur une même façon de coder.

Le choix du langage de programmation c'est tourné vers le python.

De plus vue la porté internationale d'un tel projet la totalité de la programmation sera en anglais (commentaires compris).

Les conventions adoptées qui suivent sont très largement inspirées des recommandations issue du site de python. Ces recommandations sont proposées au travers de PEP (Python Enhancement Proposal : proposition d'amélioration de Python). Pour toute zone de flou, n'hésitez pas à vous y référer et à enrichir ce wiki.

Conseil généraux

Traduction de la PEP20, issue d'openclassroom, celle-ci nous donne "l'esprit" de ce langage.

• Le beau est préférable au laid.

• L'explicite est préférable à l'implicite.

• Le simple est préférable au complexe.

• Le complexe est préférable au compliqué.

• Le plat est préférable à l'imbriqué. Moins littéralement, du code trop imbriqué (par exemple une boucle imbriquée dans une boucle imbriquée dans une boucle…) est plus difficile à lire.

• L'aéré est préférable au compact.

• La lisibilité compte.

• Les cas particuliers ne sont pas suffisamment particuliers pour casser la règle;

• Même si l'aspect pratique doit prendre le pas sur la pureté. Moins littéralement, il est difficile de faire un code à la fois fonctionnel et « pur ».

• Les erreurs ne devraient jamais passer silencieusement;

• à moins qu'elles n'aient été explicitement réduites au silence.

• En cas d'ambiguïté, résistez à la tentation de deviner.

• Il devrait exister une (et de préférence une seule) manière évidente de procéder;

• Même si cette manière n'est pas forcément évidente au premier abord.

• Maintenant est préférable à jamais.

• Mais jamais est parfois préférable à immédiatement.

• Si la mise en œuvre est difficile à expliquer, c'est une mauvaise idée.

• Si la mise en œuvre est facile à expliquer, ce peut être une bonne idée ;

• Les espaces de noms sont une très bonne idée (faisons-en plus !).

Convention de nommage

En plus d'une meilleure lisibilité, d'une collaboration plus efficace entre les programmeurs, il apparait qu'un intérêt d'adopter une convention de nommage peut être la vérification simplifiée du programme en vue d'une meilleure sécurité voir EAL [1] et [2].

Variables, fonctions et méthodes

Le nom est entièrement écrit en minuscules et les mots sont séparés par des signes soulignés (_).

nom_de_fonction.

Constantes

Les constantes doivent être écrites entièrement en majuscules, les mots étant séparés par un signe souligné (_).

NOM_DE_MA_CONSTANTE.

Régles d'écriture

Il y a deux bonnes raisons de ne pas respecter une règle donnée :

• Quand appliquer la règle rend le code moins lisible.

• Dans un souci de cohérence avec du code existant qui ne respecte pas cette règle non plus. Ce cas peut se produire si vous utilisez un module ou une bibliothèque qui ne respecte pas les mêmes conventions que celles définies ici.

Forme du code

• Indentation : utilisez 4 espaces par niveau d'indentation.
• Toujours utiliser des espaces, jamais de tabulation.
• Longueur maximum d'une ligne : limitez vos lignes à un maximum de 79 caractères. Pour les blocs de texte relativement longs (docstrings, par exemple), limitez-vous de préférence à 72 caractères par ligne.
• Découpez vos lignes en utilisant des parenthèses, crochets ou accolades plutôt que l'anti-slash \.

1 appel_d_une_fonction(parametre_1, parametre_2,
2    parametre_3, parametre_4):
3 ...

• Si vous devez découper une ligne trop longue, faites la césure après l'opérateur, pas avant.

1# Oui
2   un_long_calcul = variable + \
3           taux * 100
4   
5# Non
6   un_long_calcul = variable \
7           + taux * 100

---

index esm

• [3] conseil openclassroom

• [4] doc site de python