Quelle est la meilleure façon d'écrire Python doc string?
"""
ou "
Dans le livre Dive Into Python , l'auteur fournit l'exemple suivant:
def buildConnectionString(params):
"""Build a connection string from a dictionary of parameters.
Returns string."""
Dans un autre chapitre , l'auteur fournit un autre exemple:
def stripnulls(data):
"strip whitespace and nulls"
return data.replace("\00", "").strip()
Les deux syntaxes fonctionnent. La seule différence pour moi est que """
nous permet d'écrire un document sur plusieurs lignes.
Y a-t-il une différence autre que cela?
Extrait du PEP8 Style Guide :
PEP 257 décrit les bonnes conventions de docstring. Notez que le plus important, le "" "qui termine une chaîne de documentation multiligne doit être sur une ligne par lui-même, par exemple:
"""Return a foobang
Optional plotz says to frobnicate the bizbaz first.
"""
Pour une docstrings de liner, il est normal de conserver la fermeture "" "sur la même ligne.
PEP 257 recommande d'utiliser des guillemets triples, même pour les docstrings d'une ligne:
Notez que même la bibliothèque standard Python elle-même ne suit pas ces recommandations de manière cohérente. Par exemple,
Ce sont deux cordes, donc il n'y a pas de différence. Le style préféré est le triple guillemet double ( PEP 257 ):
Par souci de cohérence, utilisez toujours
"""triple double quotes"""
autour des docstrings.Utilisation
r"""raw triple double quotes"""
si vous utilisez des barres obliques inverses dans vos docstrings. Pour les docstrings Unicode, utilisezu"""Unicode triple-quoted strings"""
.
Non, pas vraiment. Si vous écrivez dans un fichier, l'utilisation de guillemets triples peut être idéale, car vous n'avez pas besoin d'utiliser "\ n" pour descendre d'une ligne. Assurez-vous simplement que les guillemets avec lesquels vous commencez et terminez sont du même type (guillemets doubles ou triples). Voici une ressource fiable si vous avez d'autres questions: