Pokiaľ ide o písanie čistého, dobre zdokumentovaného kódu, vývojári Pythonu majú k dispozícii tajnú zbraň – dokumentačné reťazce. Docstrings, skratka pre dokumentačné reťazce, sú životne dôležité pri sprostredkovaní účelu a funkčnosti Python funkcie, moduly a triedy.
Aké sú dokumentačné reťazce v Pythone?
Python dokumentačné reťazce (alebo dokumentačné reťazce) poskytujú pohodlný spôsob priradenia dokumentácie Python moduly funkcie, triedy a metódy. Je špecifikovaný v zdrojovom kóde, ktorý sa používa ako komentár na zdokumentovanie konkrétneho segmentu kódu. Na rozdiel od bežných komentárov k zdrojovému kódu by dokumentačný reťazec mal popisovať, čo funkcia robí, nie ako.
- Vyhlásenie Docstrings : Dokumentačné reťazce sú deklarované pomocou „trojitých jednoduchých úvodzoviek“ alebo trojitých dvojitých úvodzoviek tesne pod deklaráciou triedy, metódy alebo funkcie. Všetky funkcie by mali mať dokumentačný reťazec.
- Prístup k reťazcom dokumentov : K reťazcom dokumentov je možné pristupovať pomocou metódy __doc__ objektu alebo pomocou funkcie pomocníka. Nižšie uvedené príklady demonštrujú, ako deklarovať a získať prístup k docstringu.
Ako by mal vyzerať dokumentačný reťazec?
- Riadok reťazca dokumentu by mal začínať veľkým písmenom a končiť bodkou.
- Prvý riadok by mal byť krátky popis.
- Ak je v reťazci dokumentácie viac riadkov, druhý riadok by mal byť prázdny a vizuálne oddeľovať zhrnutie od zvyšku popisu.
- Nasledujúce riadky by mali obsahovať jeden alebo viac odsekov popisujúcich konvencie volania objektu, vedľajšie účinky atď.
Docstrings v Pythone
Nižšie sú uvedené témy, ktorým sa budeme venovať v tomto článku:
- Struny s trojitými úvodzovkami
- Dokumentačné reťazce v štýle Google
- Docstrings v štýle Numpydoc
- Jednoriadkové dokumentačné reťazce
- Viacriadkové dokumentačné reťazce
- Odsadenie v reťazcoch dokumentov
- Docstrings v triedach
- Rozdiel medzi komentármi Pythonu a docstringmi
Struny s trojitými úvodzovkami
Toto je najbežnejší formát dokumentačného reťazca v Pythone. Zahŕňa použitie trojitých úvodzoviek (buď jednoduchých alebo dvojitých) na uzavretie textu dokumentácie. Reťazce v trojitých úvodzovkách môžu zahŕňať viacero riadkov a často sú umiestnené bezprostredne pod definíciou funkcie, triedy alebo modulu
Príklad 1: Použitie trojitých jednoduchých úvodzoviek
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)> |
>
>
Výkon:
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.>
Príklad 2: Použitie trojitých dvojitých úvodzoviek
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)> |
>
>
Výkon:
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.>
Dokumentačné reťazce v štýle Google
Dokumentačné reťazce v štýle Google majú špecifický formát a sú inšpirované sprievodcom štýlov dokumentácie Google. Poskytujú štruktúrovaný spôsob dokumentovania kódu Pythonu vrátane parametrov, návratových hodnôt a popisov.
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>))> |
>
>Výkon
15>
Docstrings v štýle Numpydoc
Dokumentačné reťazce v štýle Numpydoc sa vo vedeckej komunite a komunite pre analýzu údajov široko používajú, najmä na dokumentovanie funkcií a tried súvisiacich s numerickými výpočtami a manipuláciou s údajmi. Ide o rozšírenie dokumentačných reťazcov v štýle Google s niektorými ďalšími konvenciami na dokumentovanie parametrov a návratových hodnôt.
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>))> |
>
firma vs
>Výkon
0.5>
Jednoriadkové dokumentačné reťazce
Ako už názov napovedá, jednoriadkové dokumentačné reťazce sa zmestia do jedného riadku. Používajú sa v zjavných prípadoch. Záverečné úvodzovky sú na rovnakom riadku ako úvodné úvodzovky. Toto vyzerá lepšie pre jednovrstvové. Napríklad:
Python3
def> power(a, b):> >' '> 'Returns arg1 raised to power arg2.'> ' '> > >return> a>*>*>b> print>(power.__doc__)> |
>
>
Výkon:
Returns arg1 raised to power arg2.>
Viacriadkové dokumentačné reťazce
Viacriadkové dokumentačné reťazce pozostávajú zo súhrnného riadku rovnako ako jednoriadkový dokumentačný reťazec, za ktorým nasleduje prázdny riadok, za ktorým nasleduje podrobnejší popis. Súhrnný riadok môže byť na rovnakom riadku ako úvodné úvodzovky alebo na nasledujúcom riadku. Nižšie uvedený príklad zobrazuje viacriadkový dokumentačný reťazec.
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>))> |
>
>
Výkon:
8>
Odsadenie v reťazcoch dokumentov
Celý reťazec dokumentu je odsadený rovnako ako úvodzovky v jeho prvom riadku. Nástroje na spracovanie dokumentačného reťazca odstránia z druhého a ďalších riadkov dokumentačného reťazca rovnaké množstvo odsadenia, ktoré sa rovná minimálnemu odsadeniu všetkých neprázdnych riadkov za prvým riadkom. Akékoľvek odsadenie v prvom riadku dokumentačného reťazca (t. j. až po prvý nový riadok) je bezvýznamné a je odstránené. Relatívne odsadenie neskorších riadkov v dokumentačnom reťazci sa zachová.
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)> |
>
>
Výkon:
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 v triedach
Zoberme si príklad, ktorý ukáže, ako písať reťazce docstring pre triedu a metódu „ Pomoc' sa používa na prístup k reťazcu dokumentov.
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)> |
>
>
Výkon:
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.>
Rozdiel medzi komentármi Pythonu, reťazcom a reťazcom dokumentov
Reťazec: V Pythone je reťazec sekvenciou znakov uzavretých v jednoduchých úvodzovkách (‘ ‘) alebo dvojitých úvodzovkách ( ). Reťazce sa používajú na reprezentáciu textových údajov a môžu obsahovať písmená, čísla, symboly a medzery. Sú jedným zo základných dátových typov v Pythone a možno s nimi manipulovať pomocou rôznych reťazcových metód.
Všetci ste museli mať predstavu o dokumentačných reťazcoch Pythonu, ale premýšľali ste niekedy nad tým, aký je rozdiel medzi komentármi Pythonu a dokumentačnými reťazcami? Poďme sa na ne pozrieť.
Sú to užitočné informácie, ktoré vývojári poskytujú, aby čitateľ pochopil zdrojový kód. Vysvetľuje logiku alebo jej časť použitú v kóde. Je napísaný pomocou
#>
symbolov.
Príklad:
Python3
povedal Madhuri
# Python program to demonstrate comments> print>(>'GFG'>)> name>=> 'Abhishek Shakya'> #demostrate String> |
>
>
Výkon:
GFG>
Zatiaľ čo Python Docstrings, ako je uvedené vyššie, poskytuje pohodlný spôsob spájania dokumentácie s modulmi, funkciami, triedami a metódami Pythonu.