Puhtaan, hyvin dokumentoidun koodin kirjoittamisessa Python-kehittäjillä on käytössään salainen ase – dokumenttisarjat. Dokumenttijonot, lyhenne sanoista documentation strings, ovat elintärkeitä ilmaisemaan sovelluksen tarkoitusta ja toimivuutta. Python funktiot, moduulit ja luokat.
Mitkä ovat Pythonin dokumentit?
Python dokumentaatiomerkkijonot (tai docstrings) tarjoavat kätevän tavan yhdistää dokumentaatio Python-moduulit , funktiot, luokat ja menetelmät. Se on määritelty lähdekoodissa, jota käytetään, kuten kommentti, dokumentoimaan tietty koodisegmentti. Toisin kuin perinteiset lähdekoodikommentit, dokumenttimerkkijonon tulee kuvata mitä funktio tekee, ei miten.
- Dokumenttien ilmoittaminen : Asiakirjamerkkijonot on ilmoitettu käyttämällä 'kolmoista lainausmerkkiä' tai kolminkertaisia kaksoislainausmerkkejä luokan, menetelmän tai funktion määrityksen alapuolella. Kaikilla toiminnoilla tulee olla dokumenttimerkkijono.
- Docsstringien käyttö : Dokumenttimerkkijonoihin pääsee käyttämällä objektin __doc__-metodia tai ohjetoimintoa. Alla olevat esimerkit osoittavat, kuinka dokumenttimerkkijono määritellään ja miten sitä käytetään.
Miltä docstringin pitäisi näyttää?
- Doc-merkkijonon rivin tulee alkaa isolla kirjaimella ja päättyä pisteeseen.
- Ensimmäisen rivin tulee olla lyhyt kuvaus.
- Jos dokumentaatiomerkkijonossa on enemmän rivejä, toisen rivin tulee olla tyhjä, jolloin tiivistelmä erotetaan visuaalisesti muusta kuvauksesta.
- Seuraavien rivien tulee olla yksi tai useampi kappale, joka kuvaa objektin kutsukäytäntöjä, sivuvaikutuksia jne.
Docstringit Pythonissa
Alla ovat aiheet, joita käsittelemme tässä artikkelissa:
- Kolminkertaiset lainausmerkit
- Google Style Docstrings
- Numpydoc Style Docstrings
- Yksirivinen asiakirjamerkkijono
- Moniriviset asiakirjat
- Sisennys Docsstringissä
- Docsringit luokissa
- Python-kommenttien ja dokumenttimerkkijonojen välinen ero
Kolminkertaiset lainausmerkit
Tämä on Pythonin yleisin docstring-muoto. Siinä käytetään kolminkertaisia lainausmerkkejä (joko yksi- tai kaksinkertaisia) dokumentaation tekstin liittämiseen. Kolminkertaiset lainausmerkit voivat kattaa useita rivejä, ja ne sijoitetaan usein välittömästi funktion, luokan tai moduulin määritelmän alle.
Esimerkki 1: Käytä kolminkertaisia lainausmerkkejä
Python 3
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)> |
>
>
Lähtö:
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.>
Esimerkki 2: Käytä kolminkertaisia lainausmerkkejä
Python 3
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)> |
>
>
Lähtö:
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-tyyliset asiakirjat noudattavat tiettyä muotoa, ja ne ovat saaneet vaikutteita Googlen dokumentaatiotyylioppaasta. Ne tarjoavat jäsennellyn tavan dokumentoida Python-koodia, mukaan lukien parametrit, palautusarvot ja kuvaukset.
Python 3
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>))> |
>
>Lähtö
15>
Numpydoc Style Docstrings
Numpydoc-tyylisiä dokumenttimerkkijonoja käytetään laajalti tiede- ja data-analyysiyhteisössä, erityisesti numeeriseen laskemiseen ja tietojen käsittelyyn liittyvien funktioiden ja luokkien dokumentoimiseen. Se on Google-tyyppisten asiakirjojen laajennus, jossa on joitain lisäkäytäntöjä parametrien ja palautusarvojen dokumentoimiseksi.
Python 3
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>))> |
>
>Lähtö
0.5>
Yksirivinen asiakirjamerkkijono
Kuten nimestä voi päätellä, yksiriviset asiakirjat mahtuvat yhdelle riville. Niitä käytetään ilmeisissä tapauksissa. Loppulainausmerkit ovat samalla rivillä kuin aloituslainaukset. Tämä näyttää paremmalta yksivuorisille. Esimerkiksi:
Python 3
def> power(a, b):> >' '> 'Returns arg1 raised to power arg2.'> ' '> > >return> a>*>*>b> print>(power.__doc__)> |
>
>
Lähtö:
Returns arg1 raised to power arg2.>
Moniriviset asiakirjat
Moniriviset asiakirjat koostuvat yhteenvetorivistä, kuten yksirivinen dokumenttimerkkijono, jota seuraa tyhjä rivi, jota seuraa yksityiskohtaisempi kuvaus. Yhteenvetorivi voi olla samalla rivillä kuin aloituslainaus tai seuraavalla rivillä. Alla olevassa esimerkissä näkyy monirivinen asiakirjamerkkijono.
Python 3
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>))> |
>
>
Lähtö:
8>
Sisennys Docsstringissä
Koko asiakirjamerkkijono on sisennetty samalla tavalla kuin lainausmerkit ensimmäisellä rivillään. Dokumenttimerkkijonojen käsittelytyökalut poistavat tasaisen sisennyksen dokumenttimerkkijonon toiselta ja muilta riveiltä, mikä vastaa kaikkien ensimmäisen rivin jälkeisten ei-tyhjien rivien vähimmäissisennystä. Kaikki sisennykset asiakirjan ensimmäisellä rivillä (eli ensimmäiseen uuteen riviin asti) ovat merkityksettömiä ja poistetaan. Asiakirjamerkkijonon myöhempien rivien suhteellinen sisennys säilyy.
Python 3
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)> |
kuva taustana css:ssä
>
>
Lähtö:
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.>
Docsringit luokissa
Otetaan esimerkki, kuinka kirjoitetaan dokumenttimerkkijonoja luokalle ja menetelmälle ' auta' käytetään dokumenttimerkkijonoon.
Python 3
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ähtö:
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.>
Python-kommenttien, merkkijonon ja dokumenttimerkkijonojen välinen ero
Merkkijono: Pythonissa merkkijono on merkkijono, joka on suljettu lainausmerkkien (’’) tai kaksoislainausmerkkien ( ) sisään. Merkkijonoja käytetään esittämään tekstidataa, ja ne voivat sisältää kirjaimia, numeroita, symboleja ja välilyöntejä. Ne ovat yksi Pythonin perustietotyypeistä, ja niitä voidaan käsitellä erilaisilla merkkijonomenetelmillä.
Teillä kaikilla on täytynyt olla käsitys Python-dokumenteista, mutta oletko koskaan miettinyt, mikä ero on Python-kommenttien ja docstringien välillä? Katsotaanpa niitä.
Ne ovat hyödyllisiä tietoja, joita kehittäjät tarjoavat saadakseen lukijan ymmärtämään lähdekoodin. Se selittää koodissa käytetyn logiikan tai osan siitä. Se on kirjoitettu käyttäen
#>
symboleja.
Esimerkki:
Python 3
# Python program to demonstrate comments> print>(>'GFG'>)> name>=> 'Abhishek Shakya'> #demostrate String> |
>
>
Lähtö:
GFG>
Yllä mainitut Python-dokumentit tarjoavat kätevän tavan liittää dokumentaatiota Python-moduuleihin, funktioihin, luokkiin ja menetelmiin.