Conventions syntaxiques

introduction

Cette page à pour vocation de rassembler les différentes règles de rédaction du programme ESM. Étant donné le nombre important de collaborateurs attendus 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 s'est tourné vers le python.

De plus, vue la portée 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 issues 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, méthodes et arguments

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

Modules

Les importations de modules se feront sous la forme suivantes:

import module

puis les fonctions seront ensuite appelées comme suit

module.fonction()

cette méthode permet d'éviter les conflit entre fonctions ayant le même nom.

Classes

Les classes seront écrites en PascalCase:

class NomDeClasse

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 et espaces

Indentation

Utilisez 4 espaces par niveau d'indentation, ne jamais utiliser de tabulation. Pour faciliter l'écriture du code vous pouvez configurer votre logiciel d'écriture pour qu'il insérè 4 espaces quand vous appuyer sur la touche tabulation, ainsi vous ne pourrez pas faire d'erreur lors de l'écriture. Pour notepad vous pouvez avoir accès à cette fonction dans: Paramétrage / Préférence... / Tabulation. Pour tout autre programme veuillez mettre la procédure sur le wiki une fois le problème résolu, afin d'aider les autres collaborateurs.

Espaces

Au sein du code les espaces ne devrons pas apparaitre:

• au cœur des parenthèse, accolade et crochets.
• devant une virgule, un point-virgule ou deux points.
• devant les parenthèses d'une liste de paramètres.
• plus d'un espaces pour aligner des affectations ou autre.
• autour d'un signe = si c'est une valeur par défaut d'un paramètre ou d'un appel de paramètre.

Par contre ils devrons toujours apparaitre:

• avant et après tous les opérateurs (affectation, comparaison, booléens, arithmétique)

Exemple de code correctement écrit:

spam(ham[1], {eggs: 2})
if x == 4: print x, y; x, y = y, x
spam(1)
dict['key'] = list[index]

x = 1
y = 2
long_variable = 3

i = i + 1
submitted += 1
x = x * 2 - 1
hypot2 = x * x + y * y
c = (a + b) * (a - b)

def fonction(parametre=5):
...
fonction(parametre=32)

Commentaire et chaîne de caractères

Commentaire Les docstrings devront être précédé de """ et finir par """

Les chaîne de caractère seront délimiter par des " pas par des '.

• 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

---

index esm

• [3] conseil openclassroom

• [4] doc site de python