Kaip dokumentuoti Python kodą naudojant dokumentų eilutes

Be tinkamų dokumentų gali būti sunku suprasti, prižiūrėti ir derinti kodą. „Python“ galite naudoti dokumentų eilutes, kad pateiktumėte glaustus aprašymus ir pavyzdžius, kaip kodas veikia.

Kas yra „Docstrings“?

Dokumentų eilutės yra eilutės, kurias galite pridėti prie savo Python kodo, kad paaiškintumėte, ką jis veikia ir kaip jį naudoti. Kodo dalis gali būti a Python funkcija, modulis arba klasė.

Dokumentų eilutės labai panašios į standartinius Python komentarus, tačiau jos turi tam tikrų skirtumų. Python komentarai suteikia kūrėjams papildomos informacijos apie vidinį kodo veikimą, pvz., išsamią diegimo informaciją arba įspėjimus, kuriuos reikia turėti omenyje plečiant kodą.

Kita vertus, dokumentų eilutės dažniausiai teikia informaciją kodo naudotojams, kuriems nebūtinai reikia žinoti jo diegimo detales, bet turi suprasti, ką jis daro ir kaip jį naudoti.

Kaip rašyti dokumentų eilutes

Paprastai įtraukiate dokumentų eilutes kodo, kurį norite dokumentuoti, bloko pradžioje. Turite juos sudėti trigubomis kabutėmis (). Galite rašyti vienos eilutės dokumentų eilutes arba kelių eilučių dokumentų eilutes.

Vienos eilutės dokumentų eilutės tinka paprastam kodui, kuriam nereikia daug dokumentų.

Žemiau pateikiamas funkcijos, vadinamos daugyba, pavyzdys. Dokumentų eilutė paaiškina, kad daugybos funkcija paima du skaičius, juos padaugina ir grąžina rezultatą.

defpadauginti(a, b):
Padaugina du skaičius ir grąžina rezultatą
grąžinti a * b

Sudėtingesniam kodui, kuriam reikia išsamios dokumentacijos, naudokite kelių eilučių dokumentų eilutes.

Apsvarstykite šią automobilių klasę:

klasėAutomobilis:

 A klasėatstovaujantisaautomobilisobjektas.
 Atributai:
 rida (plaukiojanti): dabartinė automobilio rida.
 Metodai:
 vairuoti (mylių): vairuoja automobilį dėl nurodytą mylių skaičių.

def__init__(savarankiškai, rida):
 savarankiškai.rida = rida
defvairuoti(savaime, mylios):

 Vairuoja mašiną dėl nurodytą mylių skaičių.
 Args:
 mylios (plaukimas): nuvažiuotų mylių skaičius.
 Grąžina:
Nė vienas

 savarankiškai.rida += mylios

Aukščiau pateiktos klasės dokumentų eilutė aprašo, ką klasė atstovauja, jos atributus ir metodus. Tuo tarpu disko metodo dokumentų eilutės pateikia informaciją apie tai, ką metodas daro, kokių argumentų jis tikisi ir ką jis grąžina.

Taip visiems, dirbantiems su šia klase, lengviau suprasti, kaip ja naudotis. Kiti dokumentų stygų naudojimo pranašumai yra šie:

• Kodo priežiūra: pateikdamos aiškų kodo veikimo aprašymą, dokumentų eilutės padeda kūrėjams keisti ir atnaujinti kodą be klaidų.
• Lengvesnis bendradarbiavimas: kai keli kūrėjai bendradarbiauja kurdami tą pačią kodo bazę, pavyzdžiui, su Visual Studio tiesioginio bendrinimo įrankis– Dokumentų eilutės leidžia kūrėjams nuosekliai dokumentuoti kodą, kad visi komandos nariai galėtų jį suprasti.
• Patobulintas kodo skaitomumas: dokumentų eilutės pateikia aukšto lygio suvestinę, ką kodas daro, kuris leidžia bet kas, skaitantis kodą, greitai supras jo paskirtį, neperžiūrėdamas viso kodo blokas.

Docstring formatai

Gera dokumentų eilutė turėtų apibūdinti, ką daro kodo dalis, argumentus, kurių jis tikisi, ir, jei reikia, įgyvendinimo detales. Tai ypač turėtų apimti visus kraštutinius atvejus, apie kuriuos turėtų žinoti visi, naudojantys kodą.

Pagrindinis dokumentų eilutės formatas turi šiuos skyrius:

• Santraukos eilutė: vienos eilutės santrauka, ką daro kodas.
• Argumentai: informacija apie argumentus, kurių tikisi funkcija, įskaitant jų duomenų tipus.
• Grąžinama vertė: informacija apie funkcijos grąžinamąją vertę, įskaitant jos duomenų tipą.
• Pakelia (neprivaloma): informacija apie visas išimtis, kurias gali sukelti funkcija.

Tai tik pagrindinis formatas, nes yra ir kitų formatų, kuriuos galite pasirinkti pagrįsti savo dokumentų eilutes. Populiariausi yra „Epytext“, „reStructuredText“ (taip pat žinomas kaip „reST“, „NumPy“) ir „Google“ dokumentų eilutės. Kiekvienas iš šių formatų turi savo sintaksę, kaip parodyta šiuose pavyzdžiuose:

Epitekstas

Dokumentų eilutė, atitinkanti Epytext formatą:

defpadauginti(a, b):

 Padauginkite du skaičius kartu.
 @param a: pirmasis skaičius, kurį reikia padauginti.
 @type a: tarpt
 @param b: antrasis skaičius, kurį reikia padauginti.
 @tipas b: tarpt
 @return: dviejų skaičių sandauga.
 @rtype: tarpt

grąžinti a * b

restruktūrizuotas tekstas (reST)

Dokumentų eilutė, kuri atitinka reST formatą:

defpadauginti(a, b):

 Padauginkite du skaičius kartu.
 :param a: Pirmasis skaičius, kurį reikia padauginti.
 :type a: tarpt
 :param b: antrasis skaičius, kurį reikia padauginti.
 :b tipas: tarpt
 :grąžinti: dviejų skaičių sandauga.
 :rtype: tarpt

grąžinti a * b

NumPy

Dokumentų eilutė, atitinkanti NumPy formatą:

defpadauginti(a, b):

 Padauginkite du skaičius kartu.
 Parametrai

 a: tarpt
 Pirmasis skaičius, kurį reikia padauginti.
 b: tarpt
 Antrasis skaičius, kurį reikia padauginti.
 Grąžina

 tarpt
 Dviejų skaičių sandauga.

grąžinti a * b

Google

Dokumentų eilutė, atitinkanti „Google“ formatą:

defpadauginti(a, b):

 Padauginkite du skaičius kartu.
 Args:
 a (int): pirmasis skaičius, kurį reikia padauginti.
 b (int): antrasis skaičius, kurį reikia padauginti.
 Grąžina:
 int: dviejų skaičių sandauga.

grąžinti a * b

Nors visi keturi docstring formatai suteikia naudingos dokumentacijos daugybos funkcijai, NumPy ir Google formatus lengviau skaityti nei Epytext ir reST formatus.

Kaip įtraukti testus į dokumentų eilutes

Testavimo pavyzdžius galite įtraukti į savo dokumentų eilutes naudodami doctest modulį. „Doctest“ modulis ieško dokumentų eilutėje teksto, kuris atrodo kaip interaktyvios „Python“ sesijos, ir tada jas vykdo, kad patikrintų, ar jie veikia taip, kaip turėtų.

Norėdami naudoti doktestus, į dokumentų eilutę įtraukite pavyzdines įvestis ir numatomas išvestis. Žemiau pateikiamas pavyzdys, kaip tai padarytumėte:

defpadauginti(a, b):

 Padauginkite du skaičius kartu.
 Parametrai

 a: tarpt
 Pirmasis skaičius, kurį reikia padauginti.
 b: tarpt
 Antrasis skaičius, kurį reikia padauginti.
 Grąžina

 tarpt
 Dviejų skaičių sandauga.
 Pavyzdžiai

 >>> dauginti(2, 3)
6
 >>> dauginti(0, 10)
0
 >>> dauginti(-1, 5)
-5

grąžinti a * b

The Pavyzdžiai Skyriuje yra trys funkcijų iškvietimai su skirtingais argumentais ir kiekvieno iš jų numatoma išvestis. Kai paleisite doctest modulį, kaip parodyta toliau, jis vykdys pavyzdžius ir palygins faktinę išvestį su numatoma išvestimi.

python -m doctest multiply.py

Jei yra skirtumų, doctest modulis praneša apie juos kaip apie gedimus. Naudodami doktestus su tokiomis dokumentų eilutėmis galite patikrinti, ar kodas veikia taip, kaip tikėtasi. Atminkite, kad doktestai nepakeičia išsamesnio vienetiniai testai ir jūsų Python kodo integravimo testai.

Kaip generuoti dokumentaciją iš „Docstrings“.

Sužinojote pagrindinius, kaip naudoti dokumentų eilutes savo Python kodui dokumentuoti, ir aukštos kokybės dokumentacijos svarbą. Norėdami tai padaryti, galbūt norėsite sugeneruoti savo modulių ir funkcijų dokumentaciją iš atitinkamų dokumentų eilučių.

Vienas iš populiariausių dokumentų generatorių, kurį galite naudoti, yra Sfinksas. Pagal numatytuosius nustatymus jis palaiko reST docstring formatą, tačiau galite sukonfigūruoti, kad jis veiktų su Google arba NumPy formatu.