Når det gjelder å skrive ren, godt dokumentert kode, har Python-utviklere et hemmelig våpen til disposisjon – docstrings. Docstrings, forkortelse for dokumentasjonsstrenger, er avgjørende for å formidle formålet og funksjonaliteten til Python funksjoner, moduler og klasser.
Hva er docstringene i Python?
Python dokumentasjonsstrenger (eller docstrings) gir en praktisk måte å knytte dokumentasjon til Python-moduler , funksjoner, klasser og metoder. Det er spesifisert i kildekoden som brukes, som en kommentar, for å dokumentere et spesifikt kodesegment. I motsetning til konvensjonelle kildekodekommentarer, skal docstringen beskrive hva funksjonen gjør, ikke hvordan.
- Erklærer Docstrings : Dokstringene er deklarert ved å bruke 'trippel enkle anførselstegn' eller trippel doble anførselstegn rett under klasse-, metode- eller funksjonserklæringen. Alle funksjoner bør ha en docstring.
- Få tilgang til Docstrings : Du kan få tilgang til docstringene ved å bruke __doc__-metoden til objektet eller ved å bruke hjelpefunksjonen. Eksemplene nedenfor viser hvordan du deklarerer og får tilgang til en docstring.
Hvordan skal en docstring se ut?
- Dok-strenglinjen skal begynne med stor bokstav og slutte med punktum.
- Den første linjen skal være en kort beskrivelse.
- Hvis det er flere linjer i dokumentasjonsstrengen, skal den andre linjen være tom, og visuelt skille sammendraget fra resten av beskrivelsen.
- Følgende linjer skal være ett eller flere avsnitt som beskriver objektets kallekonvensjoner, bivirkninger osv.
Docstrings i Python
Nedenfor er emnene vi vil dekke i denne artikkelen:
- Tredobbelt siterte strenger
- Google Style Docstrings
- Numpydoc Style Docstrings
- En-linjes Docstrings
- Flerlinjede Docstrings
- Innrykk i Docstrings
- Docstrings i klasser
- Forskjellen mellom Python-kommentarer og docstrings
Tredobbelt siterte strenger
Dette er det vanligste docstring-formatet i Python. Det innebærer å bruke tredoble anførselstegn (enten enkle eller doble) for å omslutte dokumentasjonsteksten. Strenger med tre anførselstegn kan spenne over flere linjer og er ofte plassert rett under funksjons-, klasse- eller moduldefinisjonen
Eksempel 1: Bruker trippel enkle anførselstegn
Python3
int en 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)> |
>
>
Produksjon:
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: Bruker trippel-doble 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)> |
>
>
Produksjon:
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 spesifikt format og er inspirert av Googles dokumentasjonsstilguide. De gir en strukturert måte å dokumentere Python-kode på, inkludert parametere, returverdier 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>))> |
>
>Produksjon
15>
Numpydoc Style Docstrings
Numpydoc-stil docstrings er mye brukt i det vitenskapelige og dataanalysemiljøet, spesielt for å dokumentere funksjoner og klasser relatert til numeriske beregninger og datamanipulering. Det er en utvidelse av docstrings i Google-stil, med noen tilleggskonvensjoner for å dokumentere parametere og returverdier.
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>))> |
hvordan konvertere streng til char
>
>Produksjon
0.5>
En-linjes Docstrings
Som navnet antyder passer docstrings med én linje på én linje. De brukes i åpenbare tilfeller. De avsluttende sitatene er på samme linje som de innledende sitatene. Dette ser bedre ut for one-liners. For eksempel:
Python3
def> power(a, b):> >' '> 'Returns arg1 raised to power arg2.'> ' '> > >return> a>*>*>b> print>(power.__doc__)> |
>
>
Produksjon:
Returns arg1 raised to power arg2.>
Flerlinjede Docstrings
Flerlinjede dokumentstrenger består av en oppsummeringslinje akkurat som en enlinjes dokumentstreng, etterfulgt av en tom linje, etterfulgt av en mer detaljert beskrivelse. Oppsummeringslinjen kan være på samme linje som åpningssitatene eller på neste linje. Eksemplet nedenfor viser en flerlinjet dokumentstreng.
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>))> |
>
>
Produksjon:
8>
Innrykk i Docstrings
Hele dokumentstrengen er rykket inn på samme måte som sitatene i den første linjen. Verktøy for behandling av dokumentstrenger vil fjerne en ensartet mengde innrykk fra den andre og ytterligere linje i dokumentstrengen, lik minimumsinnrykk for alle ikke-blanke linjer etter den første linjen. Eventuelle innrykk i den første linjen i dokumentstrengen (dvs. opp til den første nye linjen) er ubetydelig og fjernes. Relativ innrykk av senere linjer i docstringen beholdes.
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)> |
>
>
Produksjon:
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
La oss ta et eksempel for å vise hvordan du skriver docstrings for en klasse og metoden ' hjelp' brukes for å få tilgang 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)> |
>
>
Produksjon:
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.>
Forskjellen mellom Python-kommentarer, String og Docstrings
String: I Python er en streng en sekvens av tegn omsluttet av enkle anførselstegn (' ') eller doble anførselstegn ( ). Strenger brukes til å representere tekstdata og kan inneholde bokstaver, tall, symboler og mellomrom. De er en av de grunnleggende datatypene i Python og kan manipuleres ved hjelp av forskjellige strengmetoder.
Dere må alle ha fått en ide om Python docstrings, men har du noen gang lurt på hva som er forskjellen mellom Python-kommentarer og docstrings? La oss ta en titt på dem.
java int i streng
De er nyttig informasjon som utviklerne gir for å få leseren til å forstå kildekoden. Den forklarer logikken eller en del av den som brukes i koden. Den er skrevet ved hjelp av
#>
symboler.
Eksempel:
Python3
# Python program to demonstrate comments> print>(>'GFG'>)> name>=> 'Abhishek Shakya'> #demostrate String> |
>
>
Produksjon:
GFG>
Mens Python Docstrings som nevnt ovenfor gir en praktisk måte å knytte dokumentasjon til Python-moduler, funksjoner, klasser og metoder.