Jeśli chodzi o pisanie czystego, dobrze udokumentowanego kodu, programiści Pythona mają do dyspozycji tajną broń – dokumenty. Dokumenty, skrót od ciągów dokumentacji, są niezbędne do przekazania celu i funkcjonalności Pyton funkcje, moduły i klasy.
Jakie są dokumenty w Pythonie?
Pyton Ciągi dokumentacji (lub dokumenty) zapewniają wygodny sposób powiązania dokumentacji z Moduły Pythona , funkcje, klasy i metody. Jest to określone w kodzie źródłowym, który służy, podobnie jak komentarz, do dokumentowania określonego segmentu kodu. W przeciwieństwie do konwencjonalnych komentarzy do kodu źródłowego, dokumentacja powinna opisywać, co funkcja robi, a nie jak.
- Deklarowanie dokumentów : Dokumenty są deklarowane przy użyciu „potrójnych cudzysłowów” lub potrójnych cudzysłowów tuż pod deklaracją klasy, metody lub funkcji. Wszystkie funkcje powinny mieć dokumentację.
- Dostęp do dokumentów : Dostęp do dokumentów można uzyskać za pomocą metody __doc__ obiektu lub funkcji pomocy. Poniższe przykłady pokazują, jak zadeklarować ciąg dokumentów i uzyskać do niego dostęp.
Jak powinien wyglądać dokument?
- Wiersz ciągu dokumentu powinien zaczynać się od dużej litery i kończyć kropką.
- Pierwsza linia powinna zawierać krótki opis.
- Jeżeli w ciągu dokumentacji jest więcej wierszy, drugi wiersz powinien być pusty, wizualnie oddzielając podsumowanie od reszty opisu.
- Kolejne wiersze powinny zawierać jeden lub więcej akapitów opisujących konwencje wywoływania obiektu, skutki uboczne itp.
Dokumenty w Pythonie
Poniżej znajdują się tematy, które omówimy w tym artykule:
- Ciągi znaków w potrójnym cudzysłowie
- Dokumenty dotyczące stylu Google
- Dokumentacja w stylu Numpydoc
- Dokumenty jednowierszowe
- Dokumenty wielowierszowe
- Wcięcia w dokumentach
- Dokumenty na zajęciach
- Różnica między komentarzami w Pythonie a dokumentami
Ciągi znaków w potrójnym cudzysłowie
Jest to najpopularniejszy format ciągu dokumentów w Pythonie. Polega na użyciu potrójnych cudzysłowów (pojedynczych lub podwójnych) w celu umieszczenia tekstu dokumentacji. Ciągi znaków w potrójnych cudzysłowach mogą obejmować wiele wierszy i często są umieszczane bezpośrednio pod definicją funkcji, klasy lub modułu
Przykład 1: Używanie potrójnych cudzysłowów
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)> |
>
>
Wyjście:
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.>
Przykład 2: Używanie potrójnych cudzysłowów
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)> |
>
>
Wyjście:
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.>
Dokumenty dotyczące stylu Google
Dokumentacja w stylu Google ma określony format i jest inspirowana przewodnikiem po stylu dokumentacji Google. Zapewniają uporządkowany sposób dokumentowania kodu Pythona, w tym parametrów, wartości zwracanych i opisów.
Python3
losowe, nie w Javie
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>))> |
>
>Wyjście
15>
Dokumentacja w stylu Numpydoc
Dokumenty w stylu Numpydoc są szeroko stosowane w społeczności naukowej i zajmującej się analizą danych, szczególnie do dokumentowania funkcji i klas związanych z obliczeniami numerycznymi i manipulacją danymi. Jest to rozszerzenie dokumentów w stylu Google, z kilkoma dodatkowymi konwencjami dokumentowania parametrów i zwracanych wartości.
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>))> |
>
>Wyjście
0.5>
Dokumenty jednowierszowe
Jak sama nazwa wskazuje, jednowierszowe dokumenty mieszczą się w jednej linii. Stosuje się je w oczywistych przypadkach. Cytaty zamykające znajdują się w tej samej linii, co cytaty otwierające. Wygląda to lepiej w przypadku jednowierszowych. Na przykład:
Python3
def> power(a, b):> >' '> 'Returns arg1 raised to power arg2.'> ' '> > >return> a>*>*>b> print>(power.__doc__)> |
>
>
Wyjście:
Returns arg1 raised to power arg2.>
Dokumenty wielowierszowe
Dokumenty wieloliniowe składają się z linii podsumowania, podobnie jak ciągi dokumentów jednowierszowych, po której następuje pusta linia, po której następuje bardziej szczegółowy opis. Wiersz podsumowania może znajdować się w tym samym wierszu co cytaty otwierające lub w wierszu następnym. Poniższy przykład przedstawia wieloliniowy dokument.
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>))> |
>
>
Wyjście:
8>
Wcięcia w dokumentach
Cały dokument ma wcięcie takie samo, jak cudzysłowy w pierwszym wierszu. Narzędzia do przetwarzania dokumentów usuwają jednakową wielkość wcięcia z drugiej i kolejnych linii dokumentu, równą minimalnemu wcięciu wszystkich niepustych linii po pierwszej linii. Wszelkie wcięcia w pierwszym wierszu dokumentu (tj. do pierwszego nowego wiersza) są nieistotne i usuwane. Względne wcięcie późniejszych wierszy dokumentu zostaje zachowane.
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)> |
>
>
Wyjście:
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.>
Dokumenty na zajęciach
Weźmy przykład, aby pokazać, jak pisać dokumenty dla klasy i metody „ pomoc' służy do uzyskiwania dostępu do dokumentu.
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)> |
>
>
Wyjście:
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.>
Różnica między komentarzami w Pythonie, ciągami znaków i dokumentami
Ciąg: W Pythonie ciąg znaków to sekwencja znaków ujęta w pojedynczy cudzysłów („”) lub podwójny cudzysłów ( ). Ciągi służą do reprezentowania danych tekstowych i mogą zawierać litery, cyfry, symbole i białe znaki. Są jednym z podstawowych typów danych w Pythonie i można nimi manipulować za pomocą różnych metod łańcuchowych.
Wszyscy na pewno macie pojęcie o ciągach dokumentów w Pythonie, ale czy kiedykolwiek zastanawialiście się, jaka jest różnica między komentarzami w Pythonie a dokumentami? Przyjrzyjmy się im.
Są to przydatne informacje dostarczane przez programistów, aby czytelnik mógł zrozumieć kod źródłowy. Wyjaśnia logikę lub jej część zastosowaną w kodzie. Jest napisane za pomocą
#>
symbolika.
Przykład:
Python3
algorytm r
# Python program to demonstrate comments> print>(>'GFG'>)> name>=> 'Abhishek Shakya'> #demostrate String> |
>
>
Wyjście:
GFG>
Natomiast Python Docstrings, jak wspomniano powyżej, zapewnia wygodny sposób powiązania dokumentacji z modułami, funkcjami, klasami i metodami Pythona.