AcademyGilbak LogoAcademyGilbak

NSI · Première

Commentaires et documentation

Rendre son code lisible, documenter ses fonctions avec les docstrings et s'entraîner sur des générateurs de punitions et de tables de multiplication.

Commentaires et documentation

Les commentaires

Afin de rendre vos programmes plus clairs, il est nécessaire, dès que votre code dépasse une dizaine de lignes, d'introduire des commentaires. Les commentaires servent à expliquer votre logique aux personnes qui reliront votre code, mais également à vous rafraîchir la mémoire quelques mois plus tard.

En Python, toute ligne commençant par le caractère dièse # est considérée comme un commentaire et est ignorée par l'interpréteur.

Python
1
2
3
4
5
6
# Saisie des valeurs
cote_a = 5
cote_b = 10
# Calcul du produit (aire du rectangle)
surface = cote_a * cote_b # Un commentaire peut aussi commencer en milieu de ligne

La documentation d'une fonction (Docstring)

Toujours dans le but d'écrire du code de qualité, il est important de proposer une documentation pour vos fonctions. Une bonne documentation de fonction doit :

  1. Décrire le rôle de la fonction.
  2. Indiquer le type attendu pour les paramètres d'entrée.
  3. Spécifier le type de la valeur de retour.

La documentation se place au tout début du corps de la fonction. Elle commence par trois guillemets doubles """ et se termine par trois guillemets doubles """.

Python
1
2
3
4
5
6
7
8
9
10
11
12
def multiplication(a, b):
"""
Cette fonction permet de multiplier a par b.
Paramètres :
a (int ou float) : le premier terme
b (int ou float) : le second terme
Valeur renvoyée :
int ou float : le produit de a et b
"""
return a * b

Exercices pratiques de synthèse

Activité

Activité 1.1 : Générateur automatique de punitions

Écrire une fonction generer_punition(phrase, n) qui prend deux paramètres : une phrase (chaîne de caractères) et un nombre de répétitions n (entier).

La fonction doit afficher la phrase n fois de suite.

  • Exemple d'appel : generer_punition("Je ne dois pas discuter en classe", 3)
  • Résultat attendu :
Python
1
2
3
Je ne dois pas discuter en classe
Je ne dois pas discuter en classe
Je ne dois pas discuter en classe
Activité

Activité 1.2 : Table de multiplication

Écrire une fonction table_multiplication(table) qui prend en paramètre un nombre entier représentant la table désirée et affiche la table de 1 à 10.

  • Exemple d'appel : table_multiplication(3)
  • Résultat attendu :
Python
1
2
3
4
5
1 x 3 = 3
2 x 3 = 6
3 x 3 = 9
...
10 x 3 = 30

Résumé : Ce qu'il faut retenir

  • Variables : Association d'une valeur en mémoire à un nom. Les types de base sont int (entier), float (décimal), str (chaîne de caractères) et bool (booléen).
  • Opérations : Opérateurs arithmétiques classiques +, -, *, / et spécifiques // (division entière) ou % (reste modulo).
  • Concaténation : Assembler deux chaînes bout à bout avec le signe + ou injecter des variables avec les f-strings f"{ma_variable}".
  • Fonctions : Blocs réutilisables créés avec def et retournant des résultats avec return.
  • Conditions : Choisir quel bloc de code exécuter avec if, elif et else (les blocs de code devant être indentés).
  • Boucles : Répéter des lignes de code tant qu'une condition reste vraie avec while.

Ce qu'il faut savoir faire (Objectifs du chapitre)

  • [ ] Savoir créer et manipuler des variables en Python.
  • [ ] Savoir effectuer des calculs arithmétiques de base.
  • [ ] Savoir concaténer du texte.
  • [ ] Savoir concevoir des fonctions avec paramètres et retours de valeurs.
  • [ ] Savoir utiliser et interpréter des tests conditionnels if / elif / else.
  • [ ] Savoir lire et concevoir une boucle conditionnelle while.

Avez-vous compris ce chapitre ?

Cochez-le pour l'enregistrer dans votre progression d'apprentissage.

Chapitre précédentLa boucle whileChapitre suivantQCM : bases de Python