Как да документираме код на Python с помощта на Docstrings

Без подходяща документация може да е трудно да разберете, поддържате и отстранявате грешки в кода си. В Python можете да използвате docstrings, за да предоставите кратки описания и примери за това как работи кодът.

Какво представляват Docstrings?

Docstrings са низове, които можете да добавите към вашия код на Python, за да обясните какво прави и как да го използвате. Парчето код може да бъде a Python функция, модул или клас.

Документните низове изглеждат много като стандартни коментари на Python, но имат някои разлики. Коментарите на Python предоставят допълнителна информация на разработчиците относно вътрешната работа на кода, като подробности за изпълнението или предупреждения, които трябва да имате предвид, когато разширявате кода.

От друга страна, документните низове най-вече предоставят информация на потребителите на кода, които не е задължително да знаят подробностите за неговото изпълнение, но трябва да разберат какво прави и как да го използват.

Как да напишете Docstrings

Обикновено включвате документни низове в началото на блока от код, който искате да документирате. Трябва да ги поставите в тройни кавички (). Можете да пишете едноредови или многоредови документни низове.

Едноредовите документни низове са подходящи за прост код, който не изисква много документация.

По-долу е даден пример за функция, наречена умножение. Документационният низ обяснява, че функцията за умножение взема две числа, умножава ги и връща резултата.

дефумножават се(а, б):
Умножава две числа и връща резултата
връщане a * b

Използвайте многоредови документни низове за по-сложен код, който се нуждае от подробна документация.

Помислете за следния клас автомобили:

класКола:

 А класпредставляващаколаобект.
 Атрибути:
 пробег (float): Текущият пробег на автомобила.
 Методи:
 шофиране (мили): Кара колата за определения брой мили.

деф__в него__(самостоятелно, пробег):
 self.mileage = пробег
дефшофиране(аз, мили):

 Кара колата за определения брой мили.
 Аргументи:
 мили (плаващи): Броят мили за шофиране.
 Се завръща:
Нито един

 самостоятелен пробег += мили

Документационният низ за горния клас описва какво представлява класът, неговите атрибути и методи. Междувременно документационните низове за метода на задвижване предоставят информация за това какво прави методът, аргументите, които очаква, и какво връща.

Това улеснява всеки, който работи с този клас, да разбере как да го използва. Другите предимства от използването на документни низове включват:

• Поддържаемост на кода: Предоставяйки ясно описание на това как работи кодът, документните низове помагат на разработчиците да променят и актуализират кода, без да въвеждат грешки.
• По-лесно сътрудничество: Когато няколко разработчици си сътрудничат върху една и съща кодова база - например с Инструмент за споделяне на живо на Visual Studio—документационните низове позволяват на разработчиците да документират кода последователно, така че всеки в екипа да може да го разбере.
• Подобрена четимост на кода: Docstrings предоставят обобщение на високо ниво на това какво прави кодът и кое позволява всеки, който чете кода, за да разбере бързо неговата цел, без да преминава през целия код блок.

Формати на документни низове

Добрият docstring трябва да описва какво прави дадена част от кода, аргументите, които очаква, и подробности за изпълнението, ако е необходимо. Той трябва да включва особено всички крайни случаи, които всеки, който използва кода, трябва да знае.

Основният формат на документен низ има следните раздели:

• Обобщен ред: Резюме от един ред на това, което прави кодът.
• Аргументи: Информация за аргументите, които функцията очаква, включително техните типове данни.
• Върната стойност: Информация за върнатата стойност на функцията, включително нейния тип данни.
• Повишавания (по избор): Информация за всички изключения, които функцията може да предизвика.

Това е само основен формат, тъй като има други формати, които можете да изберете за основа на вашите документни низове. Най-популярните са Epytext, reStructuredText (известен също като reST), NumPy и Google docstrings. Всеки от тези формати има свой собствен синтаксис, както е показано в следните примери:

Epytext

Документационен низ, който следва формата на Epytext:

дефумножават се(а, б):

 Умножете две числа заедно.
 @param a: Първото число за умножение.
 @type a: int
 @param b: Второто число за умножение.
 @тип b: int
 @return: Произведението на двете числа.
 @rtype: вътрешен

връщане a * b

reStructuredText (reST)

Документационен низ, който следва формата reST:

дефумножават се(а, б):

 Умножете две числа заедно.
 :param a: Първото число за умножение.
 :тип a: int
 :param b: Второто число за умножение.
 :тип b: int
 :връщане: Произведението на двете числа.
 :rtype: int

връщане a * b

NumPy

Документационен низ, който следва формата на NumPy:

дефумножават се(а, б):

 Умножете две числа заедно.
 Параметри

 a: вътр
 Първото число за умножение.
 b: вътрешно
 Второто число за умножение.
 Се завръща

 вътр
 Произведението на двете числа.

връщане a * b

Google

Документационен низ, който следва формата на Google:

дефумножават се(а, б):

 Умножете две числа заедно.
 Аргументи:
 a (int): Първото число за умножение.
 b (int): Второто число за умножение.
 Се завръща:
 int: Произведението на двете числа.

връщане a * b

Въпреки че и четирите формата на docstring предоставят полезна документация за функцията за умножение, форматите NumPy и Google са по-лесни за четене от форматите Epytext и reST.

Как да включите тестове в Docstrings

Можете да включите примери за тестване във вашите документни низове, като използвате модула doctest. Модулът doctest търси в docstring текст, който изглежда като интерактивни сесии на Python и след това ги изпълнява, за да провери дали работят както трябва.

За да използвате doctests, включете примерните входове и очакваните резултати в docstring. По-долу е даден пример как бихте направили това:

дефумножават се(а, б):

 Умножете две числа заедно.
 Параметри

 a: вътр
 Първото число за умножение.
 b: вътрешно
 Второто число за умножение.
 Се завръща

 вътр
 Произведението на двете числа.
 Примери

 >>> умножете (2, 3)
6
 >>> умножете (0, 10)
0
 >>> умножете (-1, 5)
-5

връщане a * b

The Примери съдържа три извиквания на функции с различни аргументи и указва очаквания изход за всеки. Когато стартирате модула doctest, както е показано по-долу, той ще изпълни примерите и ще сравни действителния изход с очаквания изход.

python -m doctest multiply.py

Ако има някакви разлики, модулът doctest ги отчита като грешки. Използването на doctests с docstrings като този ви помага да проверите дали кодът работи според очакванията. Обърнете внимание, че тестовете за документи не са заместител на по-изчерпателни модулни тестове и интеграционни тестове за вашия Python код.

Как да генерирате документация от Docstrings

Научихте основите на използването на документни низове за документиране на вашия Python код и важността на висококачествената документация. За да го повишите, може да искате да генерирате документация за вашите модули и функции от съответните им документационни низове.

Един от най-популярните генератори на документация, който можете да използвате, е Sphinx. Той поддържа формат на reST docstring по подразбиране, но можете да го конфигурирате да работи с формата на Google или NumPy.