Als het gaat om het schrijven van schone, goed gedocumenteerde code, hebben Python-ontwikkelaars een geheim wapen tot hun beschikking: docstrings. Docstrings, een afkorting voor documentatiestrings, zijn essentieel voor het overbrengen van het doel en de functionaliteit van Python functies, modules en klassen.
Wat zijn de docstrings in Python?
Python documentatiestrings (of docstrings) bieden een handige manier om documentatie aan te koppelen Python-modules , functies, klassen en methoden. Het wordt gespecificeerd in de broncode en wordt, net als een opmerking, gebruikt om een specifiek stuk code te documenteren. In tegenstelling tot conventioneel broncodecommentaar moet de docstring beschrijven wat de functie doet, niet hoe.
- Docstrings declareren : De docstrings worden gedeclareerd met behulp van ‘drievoudige enkele aanhalingstekens’ of drievoudige dubbele aanhalingstekens net onder de klasse-, methode- of functiedeclaratie. Alle functies moeten een docstring hebben.
- Toegang tot Docstrings : De docstrings zijn toegankelijk via de __doc__ methode van het object of via de helpfunctie. De onderstaande voorbeelden laten zien hoe u een docstring kunt declareren en openen.
Hoe moet een docstring eruitzien?
- De documentreeksregel moet beginnen met een hoofdletter en eindigen met een punt.
- De eerste regel moet een korte beschrijving zijn.
- Als de documentatiereeks meer regels bevat, moet de tweede regel leeg zijn, waardoor de samenvatting visueel wordt gescheiden van de rest van de beschrijving.
- De volgende regels moeten uit een of meer paragrafen bestaan die de aanroepconventies, bijwerkingen, enz. van het object beschrijven.
Docstrings in Python
Hieronder staan de onderwerpen die we in dit artikel zullen behandelen:
- Tekenreeksen met drie aanhalingstekens
- Docstrings van Google-stijl
- Docstrings in Numpydoc-stijl
- Docstrings met één regel
- Docstrings met meerdere regels
- Inspringing in Docstrings
- Docstrings in klassen
- Verschil tussen Python-opmerkingen en docstrings
Tekenreeksen met drie aanhalingstekens
Dit is het meest voorkomende docstring-formaat in Python. Hierbij worden drievoudige aanhalingstekens (enkel of dubbel) gebruikt om de documentatietekst te omsluiten. Tekenreeksen tussen drie aanhalingstekens kunnen meerdere regels beslaan en worden vaak direct onder de functie-, klasse- of moduledefinitie geplaatst
Voorbeeld 1: Gebruik drievoudige enkele aanhalingstekens
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)> |
>
>
Uitgang:
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.>
Voorbeeld 2: Gebruik driedubbele aanhalingstekens
Rajesh Khanna
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)> |
>
>
Uitgang:
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 van Google-stijl
Docstrings in Google-stijl volgen een specifiek formaat en zijn geïnspireerd op de documentatiestijlgids van Google. Ze bieden een gestructureerde manier om Python-code te documenteren, inclusief parameters, retourwaarden en beschrijvingen.
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>))> |
>
wumpus wereld
>Uitvoer
15>
Docstrings in Numpydoc-stijl
Numpydoc-stijl docstrings worden veel gebruikt in de wetenschappelijke en data-analysegemeenschap, met name voor het documenteren van functies en klassen die verband houden met numerieke berekeningen en gegevensmanipulatie. Het is een uitbreiding van docstrings in Google-stijl, met enkele aanvullende conventies voor het documenteren van parameters en retourwaarden.
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>))> |
>
>Uitvoer
0.5>
Docstrings met één regel
Zoals de naam al doet vermoeden, passen docstrings van één regel op één regel. Ze worden in voor de hand liggende gevallen gebruikt. De slotaanhalingstekens staan op dezelfde regel als de openingsaanhalingstekens. Dit ziet er beter uit voor oneliners. Bijvoorbeeld:
Python3
def> power(a, b):> >' '> 'Returns arg1 raised to power arg2.'> ' '> > >return> a>*>*>b> print>(power.__doc__)> |
>
>
java int in tekenreeks
Uitgang:
Returns arg1 raised to power arg2.>
Docstrings met meerdere regels
Docstrings met meerdere regels bestaan net als een docstring van één regel uit een samenvattingsregel, gevolgd door een lege regel, gevolgd door een uitgebreidere beschrijving. De samenvattingsregel kan op dezelfde regel staan als de openingscitaten of op de volgende regel. In het onderstaande voorbeeld ziet u een docstring met meerdere regels.
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>))> |
>
>
Uitgang:
8>
Inspringing in Docstrings
De gehele docstring is op dezelfde manier ingesprongen als de aanhalingstekens op de eerste regel. Docstring-verwerkingstools verwijderen een uniforme hoeveelheid inspringing van de tweede en volgende regels van de docstring, gelijk aan de minimale inspringing van alle niet-lege regels na de eerste regel. Elke inspringing in de eerste regel van de docstring (d.w.z. tot aan de eerste nieuwe regel) is onbelangrijk en wordt verwijderd. De relatieve inspringing van latere regels in de docstring blijft behouden.
osi-referentiemodel in netwerken
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)> |
>
>
Uitgang:
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.>
Docstrings in klassen
Laten we een voorbeeld nemen om te laten zien hoe u docstrings voor een klasse schrijft en de methode ‘ hulp' wordt gebruikt om toegang te krijgen tot de docstring.
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)> |
>
>
Uitgang:
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.>
Verschil tussen Python-opmerkingen, String en Docstrings
String: In Python is een string een reeks tekens tussen enkele aanhalingstekens (‘ ‘) of dubbele aanhalingstekens ( ). Tekenreeksen worden gebruikt om tekstgegevens weer te geven en kunnen letters, cijfers, symbolen en witruimte bevatten. Ze zijn een van de fundamentele gegevenstypen in Python en kunnen worden gemanipuleerd met behulp van verschillende stringmethoden.
Jullie hebben vast allemaal een idee over Python-docstrings, maar heb je je ooit afgevraagd wat het verschil is tussen Python-opmerkingen en docstrings? Laten we ze eens bekijken.
Het zijn nuttige informatie die de ontwikkelaars verstrekken om de lezer de broncode te laten begrijpen. Het legt de logica of een deel ervan uit die in de code wordt gebruikt. Het is geschreven met behulp van
javafx-tutorial
#>
symbolen.
Voorbeeld:
Python3
# Python program to demonstrate comments> print>(>'GFG'>)> name>=> 'Abhishek Shakya'> #demostrate String> |
>
>
Uitgang:
GFG>
Terwijl Python Docstrings, zoals hierboven vermeld, een handige manier biedt om documentatie te associëren met Python-modules, functies, klassen en methoden.