Wenn es darum geht, sauberen, gut dokumentierten Code zu schreiben, steht Python-Entwicklern eine Geheimwaffe zur Verfügung – Docstrings. Docstrings, kurz für Dokumentationszeichenfolgen, sind von entscheidender Bedeutung, um den Zweck und die Funktionalität von zu vermitteln Python Funktionen, Module und Klassen.
Was sind die Dokumentzeichenfolgen in Python?
Python Dokumentationszeichenfolgen (oder Dokumentzeichenfolgen) bieten eine bequeme Möglichkeit, Dokumentation mit zu verknüpfen Python-Module , Funktionen, Klassen und Methoden. Es wird im Quellcode angegeben, der wie ein Kommentar zur Dokumentation eines bestimmten Codesegments verwendet wird. Im Gegensatz zu herkömmlichen Quellcodekommentaren sollte der Dokumentstring beschreiben, was die Funktion tut, nicht wie.
- Docstrings deklarieren : Die Dokumentzeichenfolgen werden mit „dreifachen einfachen Anführungszeichen“ oder dreifachen doppelten Anführungszeichen direkt unter der Klassen-, Methoden- oder Funktionsdeklaration deklariert. Alle Funktionen sollten einen Dokumentstring haben.
- Auf Docstrings zugreifen : Auf die Dokumentzeichenfolgen kann über die Methode __doc__ des Objekts oder über die Hilfefunktion zugegriffen werden. Die folgenden Beispiele zeigen, wie man eine Dokumentzeichenfolge deklariert und darauf zugreift.
Wie sollte ein Dokumentstring aussehen?
- Die Zeichenfolgenzeile des Dokuments sollte mit einem Großbuchstaben beginnen und mit einem Punkt enden.
- Die erste Zeile sollte eine kurze Beschreibung sein.
- Wenn die Dokumentationszeichenfolge mehr Zeilen enthält, sollte die zweite Zeile leer sein, um die Zusammenfassung optisch vom Rest der Beschreibung zu trennen.
- Die folgenden Zeilen sollten aus einem oder mehreren Absätzen bestehen, die die Aufrufkonventionen, Nebenwirkungen usw. des Objekts beschreiben.
Docstrings in Python
Nachfolgend sind die Themen aufgeführt, die wir in diesem Artikel behandeln werden:
- Strings in dreifachen Anführungszeichen
- Docstrings im Google-Stil
- Docstrings im Numpydoc-Stil
- Einzeilige Docstrings
- Mehrzeilige Docstrings
- Einrückung in Docstrings
- Dokumentzeichenfolgen in Klassen
- Unterschied zwischen Python-Kommentaren und Dokumentzeichenfolgen
Strings in dreifachen Anführungszeichen
Dies ist das gebräuchlichste Dokumentzeichenfolgenformat in Python. Dabei werden dreifache Anführungszeichen (entweder einfach oder doppelt) verwendet, um den Dokumentationstext einzuschließen. Zeichenfolgen in dreifachen Anführungszeichen können sich über mehrere Zeilen erstrecken und werden häufig direkt unter der Funktions-, Klassen- oder Moduldefinition platziert
Beispiel 1: Verwenden Sie dreifache einfache Anführungszeichen
Python3
def> my_function():> >'''Demonstrates triple double quotes> >docstrings and does nothing really.'''> > >return> None> print>(>'Using __doc__:'>)> print>(my_function.__doc__)> print>(>'Using help:'>)> help>(my_function)> |
>
>
Ausgabe:
Using __doc__: Demonstrates triple double quotes docstrings and does nothing really. Using help: Help on function my_function in module __main__: my_function() Demonstrates triple double quotes docstrings and does nothing really.>
Beispiel 2: Verwendung von Triple-Double-Anführungszeichen
Python3
Java-String enthält
def> my_function():> >' '> 'Demonstrates triple double quotes docstrings and does nothing really'> ' '> > >return> None> print>(>'Using __doc__:'>)> print>(my_function.__doc__)> print>(>'Using help:'>)> help>(my_function)> |
>
>
Ausgabe:
Using __doc__: Demonstrates triple double quotes docstrings and does nothing really. Using help: Help on function my_function in module __main__: my_function() Demonstrates triple double quotes docstrings and does nothing really.>
Docstrings im Google-Stil
Dokumentzeichenfolgen im Google-Stil folgen einem bestimmten Format und sind vom Dokumentations-Styleguide von Google inspiriert. Sie bieten eine strukturierte Möglichkeit, Python-Code zu dokumentieren, einschließlich Parametern, Rückgabewerten und Beschreibungen.
Python3
def> multiply_numbers(a, b):> >'''> >Multiplies two numbers and returns the result.> >Args:> >a (int): The first number.> >b (int): The second number.> >Returns:> >int: The product of a and b.> >'''> >return> a>*> b> print>(multiply_numbers(>3>,>5>))> |
>
>Ausgabe
15>
Docstrings im Numpydoc-Stil
Dokumentzeichenfolgen im Numpydoc-Stil werden in der Wissenschafts- und Datenanalyse-Community häufig verwendet, insbesondere zur Dokumentation von Funktionen und Klassen im Zusammenhang mit numerischen Berechnungen und Datenmanipulation. Es handelt sich um eine Erweiterung von Docstrings im Google-Stil mit einigen zusätzlichen Konventionen zum Dokumentieren von Parametern und Rückgabewerten.
Python3
def> divide_numbers(a, b):> >'''> >Divide two numbers.> >Parameters> >----------> >a : float> >The dividend.> >b : float> >The divisor.> >Returns> >-------> >float> >The quotient of the division.> >'''> >if> b>=>=> 0>:> >raise> ValueError(>'Division by zero is not allowed.'>)> >return> a>/> b> print>(divide_numbers(>3>,>6>))> |
>
>Ausgabe
Wann beginnt Q2?
0.5>
Einzeilige Docstrings
Wie der Name schon sagt, passen einzeilige Dokumentzeichenfolgen in eine Zeile. Sie werden in offensichtlichen Fällen verwendet. Die Schlusszitate stehen in derselben Zeile wie die Eröffnungszitate. Bei Einzeilern sieht das besser aus. Zum Beispiel:
Python3
def> power(a, b):> >' '> 'Returns arg1 raised to power arg2.'> ' '> > >return> a>*>*>b> print>(power.__doc__)> |
>
>
Java int im String
Ausgabe:
Returns arg1 raised to power arg2.>
Mehrzeilige Docstrings
Mehrzeilige Dokumentzeichenfolgen bestehen wie eine einzeilige Dokumentzeichenfolge aus einer Zusammenfassungszeile, gefolgt von einer Leerzeile und einer ausführlicheren Beschreibung. Die Zusammenfassungszeile kann in derselben Zeile wie die Eröffnungszitate oder in der nächsten Zeile stehen. Das folgende Beispiel zeigt einen mehrzeiligen Dokumentstring.
Python3
def> add_numbers(a, b):> >'''> >This function takes two numbers as input and returns their sum.> >Parameters:> >a (int): The first number.> >b (int): The second number.> >Returns:> >int: The sum of a and b.> >'''> >return> a>+> b> print>(add_numbers(>3>,>5>))> |
>
>
Ausgabe:
8>
Einrückung in Docstrings
Die gesamte Dokumentzeichenfolge ist genauso eingerückt wie die Anführungszeichen in der ersten Zeile. Docstring-Verarbeitungstools entfernen einen gleichmäßigen Einzug aus der zweiten und weiteren Zeilen des Docstrings, der dem minimalen Einzug aller nicht leeren Zeilen nach der ersten Zeile entspricht. Jegliche Einrückung in der ersten Zeile des Dokumentstrings (d. h. bis zur ersten neuen Zeile) ist unbedeutend und wird entfernt. Die relative Einrückung späterer Zeilen in der Dokumentzeichenfolge wird beibehalten.
Python3
class> Employee:> >'''> >A class representing an employee.> >Attributes:> >name (str): The name of the employee.> >age (int): The age of the employee.> >department (str): The department the employee works in.> >salary (float): The salary of the employee.> >'''> >def> __init__(>self>, name, age, department, salary):> >'''> >Initializes an Employee object.> >Parameters:> >name (str): The name of the employee.> >age (int): The age of the employee.> >department (str): The department the employee works in.> >salary (float): The salary of the employee.> >'''> >self>.name>=> name> >self>.age>=> age> >self>.department>=> department> >self>.salary>=> salary> >def> promote(>self>, raise_amount):> >'''> >Promotes the employee and increases their salary.> >Parameters:> >raise_amount (float): The raise amount to increase the salary.> >Returns:> >str: A message indicating the promotion and new salary.> >'''> >self>.salary>+>=> raise_amount> >return> f>'{self.name} has been promoted! New salary: ${self.salary:.2f}'> >def> retire(>self>):> >'''> >Marks the employee as retired.> >Returns:> >str: A message indicating the retirement status.> >'''> ># Some implementation for retiring an employee> >return> f>'{self.name} has retired. Thank you for your service!'> # Access the Class docstring using help()> help>(Employee)> |
>
>
Ausgabe:
class Employee | A class representing an employee. | | Attributes: | name (str): The name of the employee. | age (int): The age of the employee. | department (str): The department the employee works in. | salary (float): The salary of the employee. | | Methods defined here: | | __init__(self, name, age, department, salary) | Initializes an Employee object. | | Parameters: | name (str): The name of the employee. | age (int): The age of the employee. | department (str): The department the employee works in. | salary (float): The salary of the employee. | | promote(self, raise_amount) | Promotes the employee and increases their salary. | | Parameters: | raise_amount (float): The raise amount to increase the salary. | | Returns: | str: A message indicating the promotion and new salary. | | retire(self) | Marks the employee as retired. | | Returns: | str: A message indicating the retirement status.>
Dokumentzeichenfolgen in Klassen
Nehmen wir ein Beispiel, um zu zeigen, wie man Dokumentzeichenfolgen für eine Klasse und die Methode schreibt. helfen' wird verwendet, um auf die Dokumentzeichenfolge zuzugreifen.
Python3
class> ComplexNumber:> >'''> >This is a class for mathematical operations on complex numbers.> >Attributes:> >real (int): The real part of the complex number.> >imag (int): The imaginary part of the complex number.> >'''> >def> __init__(>self>, real, imag):> >'''> >The constructor for ComplexNumber class.> >Parameters:> >real (int): The real part of the complex number.> >imag (int): The imaginary part of the complex number.> >'''> >self>.real>=> real> >self>.imag>=> imag> >def> add(>self>, num):> >'''> >The function to add two Complex Numbers.> >Parameters:> >num (ComplexNumber): The complex number to be added.> >Returns:> >ComplexNumber: A complex number which contains the sum.> >'''> >re>=> self>.real>+> num.real> >im>=> self>.imag>+> num.imag> >return> ComplexNumber(re, im)> # Access the Class docstring using help()> help>(ComplexNumber)> # Access the method docstring using help()> help>(ComplexNumber.add)> |
>
>
Ausgabe:
Help on class ComplexNumber in module __main__: class ComplexNumber(builtins.objects) | This is a class for mathematical operations on complex numbers. | | Attributes: | real (int): The real part of complex number. | imag (int): The imaginary part of complex number. | | Methods defined here: | | __init__(self, real, imag) | The constructor for ComplexNumber class. | | Parameters: | real (int): The real part of complex number. | imag (int): The imaginary part of complex number. | | add(self, num) | The function to add two Complex Numbers. | | Parameters: | num (ComplexNumber): The complex number to be added. | | Returns: | ComplexNumber: A complex number which contains the sum. Help on method add in module __main__: add(self, num) unbound __main__.ComplexNumber method The function to add two Complex Numbers. Parameters: num (ComplexNumber): The complex number to be added. Returns: ComplexNumber: A complex number which contains the sum.>
Unterschied zwischen Python-Kommentaren, Strings und Docstrings
String: In Python ist ein String eine Folge von Zeichen, die in einfache Anführungszeichen (‘‘) oder doppelte Anführungszeichen () eingeschlossen sind. Zeichenfolgen werden zur Darstellung von Textdaten verwendet und können Buchstaben, Zahlen, Symbole und Leerzeichen enthalten. Sie gehören zu den grundlegenden Datentypen in Python und können mit verschiedenen String-Methoden manipuliert werden.
Sie alle haben bestimmt eine Vorstellung von Python-Dokumentzeichenfolgen, aber haben Sie sich jemals gefragt, was der Unterschied zwischen Python-Kommentaren und Dokumentzeichenfolgen ist? Werfen wir einen Blick darauf.
Dabei handelt es sich um nützliche Informationen, die die Entwickler bereitstellen, um dem Leser das Verständnis des Quellcodes zu erleichtern. Es erklärt die im Code verwendete Logik oder einen Teil davon. Es wird mit geschrieben
#>
Symbole.
Beispiel:
Python3
# Python program to demonstrate comments> print>(>'GFG'>)> name>=> 'Abhishek Shakya'> #demostrate String> |
>
Referenzvariable in Java
>
Ausgabe:
GFG>
Wohingegen Python-Docstrings, wie oben erwähnt, eine bequeme Möglichkeit bieten, Dokumentation mit Python-Modulen, -Funktionen, -Klassen und -Methoden zu verknüpfen.