Programmation PYTHON - Zenk - Security - Repository

202
Éléments du langage
DEUXIÈME PARTIE
De la même manière, tous les logiciels de création automatique de documentation de
code se basent sur cette fonctionnalité.
Les docstrings peuvent être écrits sur une seule ligne ou sur plusieurs lignes et sont
entourés de triples guillemets, et suivis d’un saut de ligne :
Exemple de docstring
def mimetype_to_icon(mimetype):
"""Transforme un type mime en nom de fichier icône."""
if mimetype.strip() == '':
return 'unknown.png'
return mimetype.replace('/', '_') + '.png'
Lorsqu’il est nécessaire d’écrire un texte un peu plus élaboré, il est en général conseillé
de commencer le docstring par un résumé du texte, puis de laisser un saut de
ligne entre ce titre et le corps du texte :
Exemple de docstring sur plusieurs lignes
def mimetype_to_icon(mimetype):
"""Transforme un type mime en nom de fichier icône.
Le corps du texte est aligné sur les triples guillemets et une ligne entière est réservée
au triple guillemet final.
Espacement du code
Utilisé pour les fichiers attachés. Si le type
est inconnu, renvoie 'unknown.png'.
"""
mimetype = mimetype.strip()
if mimetype == '' or mimetype notin kown_types:
return 'unknown.png'
return mimetype.replace('/', '_') + '.png'
À SAVOIR Docstring sur plusieurs lignes
Cette structure permet aux outils de documentation de différencier le titre, comparable à un docstring
sur une seule ligne, des informations complémentaires. Si elle n’est pas respectée, les documentations
générées ne seront pas très claires.
Les sauts de lignes sont un facteur de lisibilité du code non négligeable. Ils doivent
donc être utilisés à bon escient et combinés aux commentaires pour mettre en valeur
la structure du code. Dans les algorithmes complexes, un saut de ligne judicieusement
placé avant et après une boucle permet de mieux suivre le rythme, comme le
fait la ponctuation dans une phrase.