När det gäller att skriva ren, väldokumenterad kod har Python-utvecklare ett hemligt vapen till sitt förfogande – docstrings. Docstrings, förkortning för dokumentationssträngar, är avgörande för att förmedla syftet och funktionaliteten hos Pytonorm funktioner, moduler och klasser.
Vilka är docstrings i Python?
Pytonorm dokumentationssträngar (eller docstrings) ger ett bekvämt sätt att associera dokumentation med Python-moduler , funktioner, klasser och metoder. Det är specificerat i källkoden som används, som en kommentar, för att dokumentera ett specifikt kodsegment. Till skillnad från konventionella källkodskommentarer ska docstringen beskriva vad funktionen gör, inte hur.
- Deklarerar Docstrings : Doksträngarna deklareras med 'trippel enkla citattecken' eller trippel dubbla citattecken precis under klass-, metod- eller funktionsdeklarationen. Alla funktioner bör ha en docstring.
- Åtkomst till Docstrings : docstrings kan nås med hjälp av __doc__-metoden för objektet eller med hjälp av hjälpfunktionen. Exemplen nedan visar hur man deklarerar och får åtkomst till en docstring.
Hur ska en docstring se ut?
- Dokumentsträngsraden ska börja med stor bokstav och sluta med punkt.
- Den första raden ska vara en kort beskrivning.
- Om det finns fler rader i dokumentationssträngen ska den andra raden vara tom, vilket visuellt skiljer sammanfattningen från resten av beskrivningen.
- Följande rader ska vara ett eller flera stycken som beskriver objektets anropskonventioner, biverkningar etc.
Docstrings i Python
Nedan är de ämnen som vi kommer att ta upp i den här artikeln:
- Strängar med tre citat
- Google Style Docstrings
- Numpydoc Style Docstrings
- Enrads Docstrings
- Flerradiga Docstrings
- Indrag i Docstrings
- Docstrings i klasser
- Skillnad mellan Python-kommentarer och docstrings
Strängar med tre citat
Detta är det vanligaste docstring-formatet i Python. Det innebär att man använder tredubbla citattecken (antingen enkla eller dubbla) för att bifoga dokumentationstexten. Strängar med tre citattecken kan sträcka sig över flera rader och placeras ofta omedelbart under funktions-, klass- eller moduldefinitionen
Exempel 1: Använder trippel enkla citattecken
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)> |
>
lexikografiskt
>
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.>
Exempel 2: Använder trippel-dubbla citattecken
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öljer ett specifikt format och är inspirerade av Googles dokumentationsstilsguide. De tillhandahåller ett strukturerat sätt att dokumentera Python-kod, inklusive parametrar, returvärden och beskrivningar.
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>))> |
>
giltiga identifierare i java
>Produktion
15>
Numpydoc Style Docstrings
Numpydoc-liknande docstrings används ofta inom vetenskaps- och dataanalysgemenskapen, särskilt för att dokumentera funktioner och klasser relaterade till numeriska beräkningar och datamanipulation. Det är en förlängning av docstrings i Google-stil, med några ytterligare konventioner för att dokumentera parametrar och returvärden.
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>))> |
>
>Produktion
0.5>
Enrads Docstrings
Som namnet antyder passar enrads docstrings på en rad. De används i uppenbara fall. De avslutande citaten är på samma rad som de inledande citaten. Detta ser bättre ut för one-liners. Till exempel:
Python3
def> power(a, b):> >' '> 'Returns arg1 raised to power arg2.'> ' '> > >return> a>*>*>b> print>(power.__doc__)> |
>
>
java int i sträng
Produktion:
Returns arg1 raised to power arg2.>
Flerradiga Docstrings
Flerradiga docstrings består av en sammanfattningsrad precis som en enrads docstring, följt av en tom rad, följt av en mer utförlig beskrivning. Sammanfattningsraden kan vara på samma rad som inledande citat eller på nästa rad. Exemplet nedan visar en flerrads 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>))> |
>
binär till bcd
>
Produktion:
8>
Indrag i Docstrings
Hela docstringen är indragen på samma sätt som citattecken på den första raden. Verktyg för bearbetning av dokumentsträngar tar bort en enhetlig mängd indrag från den andra och ytterligare raderna i dokumentsträngen, lika med den minsta indragningen av alla icke-tomma rader efter den första raden. Alla indrag i den första raden i docstringen (dvs. upp till den första nya raden) är obetydlig och tas bort. Relativ indragning av senare rader i docstringen behålls.
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
Låt oss ta ett exempel för att visa hur man skriver docstrings för en klass och metoden ' hjälp' används för att komma åt 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)> |
>
länkad lista i java
>
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.>
Skillnad mellan Python-kommentarer, String och Docstrings
Sträng: I Python är en sträng en sekvens av tecken omslutna av enkla citattecken (' ') eller dubbla citattecken ( ). Strängar används för att representera textdata och kan innehålla bokstäver, siffror, symboler och blanksteg. De är en av de grundläggande datatyperna i Python och kan manipuleras med olika strängmetoder.
Ni måste alla ha fått en uppfattning om Python docstrings men har ni någonsin undrat vad är skillnaden mellan Python kommentarer och docstrings? Låt oss ta en titt på dem.
De är användbar information som utvecklarna tillhandahåller för att få läsaren att förstå källkoden. Det förklarar logiken eller en del av den som används i koden. Det är skrivet med hjälp av
#>
symboler.
Exempel:
Python3
# Python program to demonstrate comments> print>(>'GFG'>)> name>=> 'Abhishek Shakya'> #demostrate String> |
>
>
Produktion:
GFG>
Medan Python Docstrings som nämnts ovan ger ett bekvämt sätt att associera dokumentation med Python-moduler, funktioner, klasser och metoder.