Når det kommer til at skrive ren, veldokumenteret kode, har Python-udviklere et hemmeligt våben til deres rådighed – docstrings. Docstrings, forkortelse for dokumentationsstrenge, er afgørende for at formidle formålet og funktionaliteten af Python funktioner, moduler og klasser.
Hvad er docstrings i Python?
Python dokumentationsstrenge (eller docstrings) giver en bekvem måde at knytte dokumentation til Python moduler , funktioner, klasser og metoder. Det er angivet i kildekoden, der bruges, ligesom en kommentar, til at dokumentere et specifikt kodesegment. I modsætning til konventionelle kildekodekommentarer skal docstringen beskrive, hvad funktionen gør, ikke hvordan.
- Erklærer Docstrings : Dokstringerne er erklæret ved hjælp af 'triple single quotes' eller triple double quotes lige under klasse-, metode- eller funktionserklæringen. Alle funktioner skal have en docstring.
- Adgang til Docstrings : Der kan tilgås docstrings ved hjælp af __doc__ metoden for objektet eller ved hjælp af hjælpefunktionen. Nedenstående eksempler viser, hvordan man deklarerer og får adgang til en docstring.
Hvordan skal en docstring se ud?
- Doc-strenglinjen skal begynde med et stort bogstav og slutte med et punktum.
- Den første linje skal være en kort beskrivelse.
- Hvis der er flere linjer i dokumentationsstrengen, skal den anden linje være tom og visuelt adskille resuméet fra resten af beskrivelsen.
- De følgende linjer skal være et eller flere afsnit, der beskriver objektets kaldekonventioner, bivirkninger osv.
Docstrings i Python
Nedenfor er de emner, som vi vil dække i denne artikel:
- Strenge med tre citater
- Google Style Docstrings
- Numpydoc Style Docstrings
- One-line Docstrings
- Multi-line Docstrings
- Indrykning i Docstrings
- Docstrings i klasser
- Forskellen mellem Python-kommentarer og docstrings
Strenge med tre citater
Dette er det mest almindelige docstring-format i Python. Det involverer at bruge tredobbelte anførselstegn (enten enkelt eller dobbelt) til at omslutte dokumentationsteksten. Strenge med tre citater kan spænde over flere linjer og placeres ofte umiddelbart under funktions-, klasse- eller moduldefinitionen
Eksempel 1: Brug af tredobbelte enkelte anførselstegn
Python3
konverter heltal til streng java
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)> |
>
>
Produktion:
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.>
Eksempel 2: Brug af tredobbelte anførselstegn
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)> |
>
>
Produktion:
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.>
Google Style Docstrings
Google-stil-docstrings følger et bestemt format og er inspireret af Googles dokumentationsstilguide. De giver en struktureret måde at dokumentere Python-kode på, herunder parametre, returværdier og beskrivelser.
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>))> |
>
>Produktion
15>
Numpydoc Style Docstrings
Numpydoc-stil docstrings bruges i vid udstrækning i det videnskabelige og dataanalysesamfund, især til at dokumentere funktioner og klasser relateret til numeriske beregninger og datamanipulation. Det er en udvidelse af Google-stil docstrings, med nogle yderligere konventioner til at dokumentere parametre og returværdier.
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>))> |
objekt til jsonobject java
>
>Produktion
0.5>
One-line Docstrings
Som navnet antyder, passer docstrings på én linje i én linje. De bruges i åbenlyse tilfælde. De afsluttende citater er på samme linje som de indledende citater. Dette ser bedre ud for one-liners. For eksempel:
Python3
def> power(a, b):> >' '> 'Returns arg1 raised to power arg2.'> ' '> > >return> a>*>*>b> print>(power.__doc__)> |
>
>
Produktion:
Returns arg1 raised to power arg2.>
Multi-line Docstrings
Flerlinjede docstrings består af en oversigtslinje ligesom en docstring på én linje, efterfulgt af en tom linje efterfulgt af en mere udførlig beskrivelse. Opsummeringslinjen kan være på samme linje som de indledende citater eller på den næste linje. Eksemplet nedenfor viser en flerlinjet docstring.
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>))> |
>
>
Produktion:
8>
Indrykning i Docstrings
Hele docstringen er indrykket på samme måde som citaterne i dens første linje. Værktøjer til behandling af docstring vil fjerne en ensartet mængde af indrykning fra den anden og yderligere linjer i docstringen, svarende til minimumsindrykningen af alle ikke-blanke linjer efter den første linje. Enhver indrykning i den første linje af docstringen (dvs. op til den første nye linje) er ubetydelig og fjernes. Relativ indrykning af senere linjer i docstringen bibeholdes.
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)> |
>
>
Produktion:
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 i klasser
Lad os tage et eksempel for at vise, hvordan man skriver docstrings for en klasse og metoden ' Hjælp' bruges til at få adgang til docstringen.
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)> |
>
>
Produktion:
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.>
Forskel mellem Python-kommentarer, String og Docstrings
String: I Python er en streng en sekvens af tegn omsluttet af enkelte anførselstegn (' ') eller dobbelte anførselstegn ( ). Strenge bruges til at repræsentere tekstdata og kan indeholde bogstaver, tal, symboler og mellemrum. De er en af de grundlæggende datatyper i Python og kan manipuleres ved hjælp af forskellige strengmetoder.
I må alle have fået en idé om Python docstrings, men har du nogensinde spekuleret på, hvad er forskellen mellem Python-kommentarer og docstrings? Lad os se på dem.
java int i streng
De er nyttige oplysninger, som udviklerne giver for at få læseren til at forstå kildekoden. Det forklarer logikken eller en del af den brugt i koden. Det er skrevet vha
#>
symboler.
Eksempel:
Python3
# Python program to demonstrate comments> print>(>'GFG'>)> name>=> 'Abhishek Shakya'> #demostrate String> |
>
>
Produktion:
GFG>
Hvorimod Python Docstrings som nævnt ovenfor giver en bekvem måde at forbinde dokumentation med Python-moduler, funktioner, klasser og metoder.