Kai reikia rašyti švarų, gerai dokumentuotą kodą, Python kūrėjai disponuoja slaptu ginklu – dokumentais. Dokumentų eilutės, sutrumpintos dokumentacijos eilutės, yra labai svarbios norint perteikti programos paskirtį ir funkcionalumą. Python funkcijos, moduliai ir klasės.
Kokios yra Python dokumentų eilutės?
Python dokumentacijos eilutės (arba dokumentų eilutės) yra patogus būdas susieti dokumentus su Python moduliai , funkcijos, klasės ir metodai. Jis nurodytas šaltinio kode, kuris naudojamas kaip komentaras tam tikram kodo segmentui dokumentuoti. Skirtingai nuo įprastų šaltinio kodo komentarų, dokumentų eilutė turėtų aprašyti, ką funkcija atlieka, o ne kaip.
- Dokumentų eilučių deklaravimas : Dokumentų eilutės deklaruojamos naudojant „trigubas pavienes kabutes“ arba trigubas dvigubas kabutes tiesiai po klasės, metodu arba funkcijos deklaracija. Visos funkcijos turi turėti dokumentų eilutę.
- Prieiga prie dokumentų eilučių : Dokumentų eilutes galima pasiekti naudojant objekto __doc__ metodą arba pagalbos funkciją. Toliau pateikti pavyzdžiai parodo, kaip deklaruoti ir pasiekti dokumentų eilutę.
Kaip turėtų atrodyti doktrina?
- Dokumento eilutės eilutė turėtų prasidėti didžiąja raide ir baigtis tašku.
- Pirmoje eilutėje turėtų būti trumpas aprašymas.
- Jei dokumentacijos eilutėje yra daugiau eilučių, antroji eilutė turi būti tuščia, vizualiai atskiriant santrauką nuo likusios aprašo dalies.
- Šios eilutės turėtų būti viena ar kelios pastraipos, kuriose aprašomos objekto iškvietimo taisyklės, šalutiniai poveikiai ir kt.
„Docstrings“ Python
Žemiau pateikiamos temos, kurias aptarsime šiame straipsnyje:
- Trigubos kabutės
- „Google“ stiliaus dokumentų eilutės
- Numpydoc stiliaus dokumentų eilutės
- Vienos eilutės dokumentų eilutės
- Kelių eilučių dokumentų eilutės
- Įtrauka dokumentų eilutėse
- Dokumentų eilutės pamokose
- Skirtumas tarp Python komentarų ir dokumentų stygų
Trigubos kabutės
Tai yra labiausiai paplitęs Python dokumentų eilutės formatas. Tai apima trijų kabučių (vienkartinių arba dvigubų) naudojimą dokumentacijos tekstui pridėti. Trijų kabučių eilutės gali apimti kelias eilutes ir dažnai yra iškart po funkcijos, klasės ar modulio apibrėžimu.
1 pavyzdys: Naudojant trigubas pavienes kabutes
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)> |
skaičių abėcėlė
>
>
Išvestis:
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.>
2 pavyzdys: Naudojant trigubas dvigubas kabutes
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)> |
>
>
Išvestis:
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“ stiliaus dokumentų eilutės
„Google“ stiliaus dokumentų eilutės atitinka tam tikrą formatą ir yra įkvėptos „Google“ dokumentacijos stiliaus vadovo. Jie suteikia struktūrinį Python kodo dokumentavimo būdą, įskaitant parametrus, grąžinimo reikšmes ir aprašymus.
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>))> |
>
niūri kalba
>Išvestis
15>
Numpydoc stiliaus dokumentų eilutės
Numpydoc stiliaus dokumentai plačiai naudojami mokslo ir duomenų analizės bendruomenėje, ypač dokumentuojant funkcijas ir klases, susijusias su skaitiniais skaičiavimais ir duomenų apdorojimu. Tai yra „Google“ tipo dokumentų stygų plėtinys su kai kuriais papildomais parametrų ir grąžinamų verčių dokumentavimo susitarimais.
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>))> |
>
>Išvestis
0.5>
Vienos eilutės dokumentų eilutės
Kaip rodo pavadinimas, vienos eilutės dokumentų eilutės telpa vienoje eilutėje. Jie naudojami akivaizdžiais atvejais. Baigimo kabutės yra toje pačioje eilutėje kaip ir pradžios kabutės. Tai geriau atrodo vieno įdėklams. Pavyzdžiui:
Python3
def> power(a, b):> >' '> 'Returns arg1 raised to power arg2.'> ' '> > >return> a>*>*>b> print>(power.__doc__)> |
>
>
pavadinkite miestą JAV
Išvestis:
Returns arg1 raised to power arg2.>
Kelių eilučių dokumentų eilutės
Kelių eilučių dokumentų eilutes sudaro suvestinės eilutė, kaip ir vienos eilutės dokumentų eilutė, po kurios seka tuščia eilutė, po kurios seka išsamesnis aprašymas. Santraukos eilutė gali būti toje pačioje eilutėje kaip pradžios kabutės arba kitoje eilutėje. Toliau pateiktame pavyzdyje parodyta kelių eilučių dokumentų eilutė.
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>))> |
.net pamoka
>
>
Išvestis:
8>
Įtrauka dokumentų eilutėse
Visa dokumento eilutė yra įtraukta taip pat, kaip ir kabutės pirmoje eilutėje. Dokumentų eilutės apdorojimo įrankiai pašalins vienodą įtrauką iš antrosios ir tolesnių eilučių eilučių, lygių minimaliai visų netuščių eilučių įtraukai po pirmosios eilutės. Bet kokia įtrauka pirmoje dokumento eilutės eilutėje (t. y. iki pirmosios naujos eilutės) yra nereikšminga ir pašalinta. Santykinė vėlesnių eilučių įtrauka dokumentinėje eilutėje išlaikoma.
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)> |
>
>
Išvestis:
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.>
Dokumentų eilutės klasėse
Paimkime pavyzdį, kad parodytume, kaip parašyti dokumentų eilutes klasei ir metodui ' padėti' naudojamas norint pasiekti dokumentų eilutę.
Python3
nuskaityti.nextstring java
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)> |
>
>
Išvestis:
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.>
Skirtumas tarp Python komentarų, eilutės ir dokumentų eilučių
Eilutė: Python programoje eilutė yra simbolių seka, įterpta į pavienes kabutes (‘‘) arba dvigubas kabutes ( ). Teksto duomenims pavaizduoti naudojamos eilutės, kuriose gali būti raidžių, skaičių, simbolių ir tarpų. Jie yra vienas iš pagrindinių Python duomenų tipų ir jais galima manipuliuoti naudojant įvairius eilučių metodus.
Jūs visi tikriausiai turėjote idėją apie Python dokumentų eilutes, bet ar kada nors susimąstėte, kuo skiriasi Python komentarai ir dokumentų eilutės? Pažvelkime į juos.
Tai naudinga informacija, kurią kūrėjai pateikia, kad skaitytojas suprastų šaltinio kodą. Jame paaiškinama kode naudojama logika arba jos dalis. Parašyta naudojant
#>
simboliai.
Pavyzdys:
Python3
# Python program to demonstrate comments> print>(>'GFG'>)> name>=> 'Abhishek Shakya'> #demostrate String> |
>
>
Išvestis:
GFG>
Tuo tarpu Python Docstrings, kaip minėta pirmiau, yra patogus būdas susieti dokumentus su Python moduliais, funkcijomis, klasėmis ir metodais.