Analyse du code de spécification de commentaire de code Python

1. Introduction aux commentaires de code

• Les commentaires sont des explications et des explications du code, et leur but est de faciliter la compréhension du code par les gens.
• Les commentaires se produisent lorsque le programmeur écrit une explication ou un indice pour une instruction, un segment de programme, une fonction, etc., ce qui peut améliorer la lisibilité du code du programme.

• Dans le code avec logique de traitement, la quantité de commentaires effectifs dans le programme source doit être supérieure à 20 %.

Recommandations d'apprentissage associées : Tutoriel vidéo Python

Classification des commentaires de code

Commentaire de ligne : La ligne après le symbole ne sera pas compilée (affichée)

Commentaire de bloc : La partie au milieu du symbole de commentaire de bloc ne sera pas compilé Compiler

3. Bases des commentaires de code python

# est utilisé en Python pour représenter un seul commentaires en ligne. Les commentaires sur une seule ligne peuvent être placés sur une ligne distincte au-dessus de la ligne de code commentée, ou après une instruction ou une expression. L'exemple suivant :

name = 'xiaohong' # Commentaire sur une seule ligne

# Commentaire sur une seule ligne

name = 'xiaohong'

Utilisez trois guillemets simples ou trois guillemets doubles en Python pour indiquer des commentaires sur plusieurs lignes. Utilisé lorsqu'il y a trop de commentaires à écrire, comme dans l'exemple suivant :

'''

Il s'agit d'un commentaire sur plusieurs lignes utilisant trois guillemets simples
'' '

"""

Ceci est un commentaire sur plusieurs lignes utilisant trois guillemets doubles
"""

4. Introduction et utilisation des DocStrings

4.1 Introduction aux DocStrings

Les chaînes de documents

sont un outil important pour l'interprétation programmes de documentation. Aidez la documentation de votre programme à être plus simple et plus facile à comprendre

4.2 Utiliser DocStrings en python

Utilisez une paire de trois guillemets simples ''' ou une paire de trois dans la première ligne du corps de la fonction Des guillemets doubles """ pour définir la docstring. Vous pouvez utiliser doc (notez le double trait de soulignement) pour appeler l'attribut docstring dans la fonction.

L'exemple d'écriture est le suivant :

def add(num1,num2):
  """ 完成传入的两个数之和

  :param num1: 加数1
  :param num2: 加数2
  :return: 和
  """
  return num1 + num2

print( add.__doc__ )

Remarques : Convention d'utilisation de la chaîne de document DocStrings : sa première ligne décrit brièvement la fonction, la deuxième ligne est vide et la troisième ligne est une description spécifique de la fonction 5. Styles d'écriture courants de DocStrings <🎜. >.

Style reST 5.1 C'est un style populaire maintenant, le style reST, le format standard de Sphinx, qui est relativement compact >5.2 Google. style

"""
This is a reST style.

:param param1: this is a first param
:param param2: this is a second param
:returns: this is a description of what is returned
:raises keyError: raises an exception
"""

5.3 Numpydoc (style Numpy)

"""
This is a groups style docs.

Parameters:
 param1 - this is the first param
 param2 - this is a second param

Returns:
 This is a description of what is returned

Raises:
 KeyError - raises an exception
"""

6. Une certaine expérience d'annotation

Plus il y a de commentaires. , mieux c'est. Pour un code clair en un coup d'œil, il n'est pas nécessaire d'ajouter des commentaires

Pour les opérations complexes, les commentaires correspondants doivent être écrits avant le démarrage de l'opération. . , les commentaires doivent être ajoutés après le code. Ne décrivez jamais le code. Les personnes qui lisent le code connaissent généralement la syntaxe de Python, mais ne savent pas ce que fait le code. >Apprentissage connexe. Recommandé : Vidéo de programmation

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!