Како документовати Питхон код помоћу низова докумената

Без одговарајуће документације, може бити тешко разумети, одржавати и отклањати грешке у вашем коду. У Питхон-у можете да користите низове докумената да бисте пружили сажете описе и примере како код функционише.

Шта су низови докумената?

Доцстрингс су стрингови које можете додати свом Питхон коду да бисте објаснили шта ради и како да га користите. Комад кода може бити а Питхон функција, модул или класа.

Доцстрингс личе на стандардне Питхон коментаре, али имају неке разлике. Питхон коментари пружају додатне информације програмерима о унутрашњем функционисању кода, као што су детаљи имплементације или упозорења која треба имати на уму приликом проширења кода.

С друге стране, доцстрингс углавном пружају информације корисницима кода који можда не морају нужно да знају детаље о његовој имплементацији, али морају да разумеју шта он ради и како да га користе.

Како писати низове докумената

Обично укључујете низове докумената на почетку блока кода који желите да документујете. Морате их ставити у троструке наводнике (). Можете писати низове докумената у једном реду или низове докумената у више редова.

Низови докумената у једном реду су погодни за једноставан код који не захтева много документације.

Испод је пример функције која се зове мултипли. Док-стринг објашњава да функција множења узима два броја, множи их и враћа резултат.

дефумножити(а, б):
Множи два броја и враћа резултат
повратак а * б

Користите низове докумената у више редова за сложенији код за који је потребна детаљна документација.

Размотрите следећу класу аутомобила:

класаАуто:

 А класапредстављањеааутообјекат.
 Атрибути:
 километража (флоат): Тренутна километража аутомобила.
 Методе:
 возити (миљама): Вози аутомобил за наведени број миља.

деф__у томе__(ја, километража):
 селф.километража = километража
дефпогон(сам, миље):

 Вози ауто за наведени број миља.
 Аргс:
 миље (флоат): број миља за вожњу.
 враћа:
Ниједан

 селф.километража += миља

Докстринг за горњу класу описује шта класа представља, њене атрибуте и методе. У међувремену, доцстрингс за диск метод пружају информације о томе шта метода ради, аргументима које очекује и шта враћа.

Ово олакшава свима који раде са овом класом да схвате како да је користе. Остале предности коришћења низова докумената укључују:

• Одржавање кода: Пружајући јасан опис како код функционише, низови докумената помажу програмерима да модификују и ажурирају код без уношења грешака.
• Лакша сарадња: Када неколико програмера сарађује на истој бази кода – на пример, са Висуал Студио алатка за дељење уживо—доцстрингс омогућавају програмерима да доследно документују код како би сви у тиму могли да га разумеју.
• Побољшана читљивост кода: Доцстрингс пружају сажетак високог нивоа онога што код ради што дозвољава свако ко чита код да брзо разуме његову сврху без проласка кроз цео код блокирати.

Доцстринг Форматс

Добар низ докумената треба да описује шта део кода ради, аргументе које очекује и детаље имплементације ако је потребно. То би посебно требало да обухвати све ивичне случајеве којих би свако ко користи код требало да зна.

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

• Резиме: Резиме у једном реду онога што код ради.
• Аргументи: Информације о аргументима које функција очекује укључујући њихове типове података.
• Повратна вредност: Информације о повратној вредности функције укључујући њен тип података.
• Раисес (опционо): Информације о свим изузецима које функција може да покрене.

Ово је само основни формат јер постоје и други формати које можете изабрати да бисте базирали своје документе. Најпопуларнији су Епитект, реСтруцтуредТект (познат и као реСТ), НумПи и Гоогле доцстрингс. Сваки од ових формата има своју синтаксу као што је приказано у следећим примерима:

Епитект

Низ документа који прати формат Епитект:

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

 Помножите два броја заједно.
 @парам а: Први број за множење.
 @типе а: инт
 @парам б: Други број за множење.
 @тип б: инт
 @ретурн: производ два броја.
 @ртипе: инт

повратак а * б

реСтруцтуредТект (реСТ)

Низ документа који прати реСТ формат:

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

 Помножите два броја заједно.
 :парам а: Први број за множење.
 :типе а: инт
 :парам б: Други број за множење.
 :тип б: инт
 :повратак: производ два броја.
 :ртипе: инт

повратак а * б

НумПи

Низ документа који прати НумПи формат:

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

 Помножите два броја заједно.
 Параметерс

 а: инт
 Први број за множење.
 б: инт
 Други број за множење.
 Повратак

 инт
 Производ два броја.

повратак а * б

Гоогле

Низ документа који прати Гоогле формат:

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

 Помножите два броја заједно.
 Аргс:
 а (инт): Први број за множење.
 б (инт): Други број за множење.
 враћа:
 инт: производ два броја.

повратак а * б

Иако сва четири формата низова докумената пружају корисну документацију за функцију множења, НумПи и Гоогле формати су лакши за читање него Епитект и реСТ формати.

Како укључити тестове у низове докумената

Можете укључити примере тестирања у своје документе користећи модул доцтест. Модул доцтест претражује доцстринг за текст који изгледа као интерактивне Питхон сесије, а затим их извршава да би проверио да ли раде како треба.

Да бисте користили доцтестове, укључите узорке улаза и очекиваних излаза у доцстринг. Испод је пример како бисте то урадили:

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

 Помножите два броја заједно.
 Параметерс

 а: инт
 Први број за множење.
 б: инт
 Други број за множење.
 Повратак

 инт
 Производ два броја.
 Примери

 >>> помножи (2, 3)
6
 >>> помножи (0, 10)
0
 >>> помножи (-1, 5)
-5

повратак а * б

Тхе Примери одељак садржи три позива функције са различитим аргументима и специфицира очекивани излаз за сваки. Када покренете доцтест модул као што је приказано испод, он ће извршити примере и упоредити стварни излаз са очекиваним излазом.

питхон -м доцтест мултипли.пи

Ако постоје било какве разлике, модул доцтест их пријављује као грешке. Коришћење доцтестова са оваквим низовима докумената помаже вам да проверите да ли код ради како се очекује. Имајте на уму да доктестови нису замена за свеобухватније јединични тестови и тестови интеграције за ваш Питхон код.

Како генерисати документацију из низова докумената

Научили сте основе коришћења низова докумената за документовање вашег Питхон кода и важност висококвалитетне документације. Да бисте то напредовали, можда ћете желети да генеришете документацију за своје модуле и функције из њихових одговарајућих низова докумената.

Један од најпопуларнијих генератора документације који можете користити је Спхинк. Подразумевано подржава реСТ доцстринг формат, али га можете конфигурисати да ради са Гоогле или НумПи форматом.