Kuna me juba teame, kuidas mitmerealisi kommentaare kirjutada, võime kasutada kas kolmekordseid üksikjutumärke või kolmekordseid jutumärke. Kasutame dokumentatsioonistringi, kui tahame oma funktsioone kirjeldada, et saaksime dokumentatsiooni siis, kui seda vajame. Mõned IDE-d pakuvad teile dokumentatsiooni, hõljutades kursorit nime kohal, ja mõned tõstavad esile teatud märksõnad. Kuid tõsiasi on see, et NumPy dokumendistringid on palju paindlikumad kui teistes keeltes. Docstring on stringliteraal, mis esineb funktsiooni määratluse alguses. Dokumendistringide kasutamisel funktsioonide, klasside jms puhul peame esitama konkreetsed väärtused.
Funktsioonidega docstringide kasutamisel peame argumendid edastama. Kasutades neid klassidega, anname edasi atribuudid ja meetodid. Moodulite puhul peame esitama klasside ja funktsioonide loendi. Paketi puhul edastame funktsionaalsusega moodulite nimekirja. Põhimõtteliselt on dokstringi eesmärk, nagu nimigi selgitab, see, et see aitab meie koodi dokumenteerida. Teeme dokumentatsiooni selleks, et kui keegi tulevikus meie koodi kasutab, saaks ta docstringi abil aru meie koodist ja koodi taga olevast loogikast. Sisseehitatud funktsioonidel on ka dokstringid; saame kasutada funktsiooni help(), et vaadata sisseehitatud funktsioonide dokstringi.
Kommentaaride ja dokumentide vahel on mõned erinevused. Tõlgid eiravad kommentaare, kuid tõlgid ei ignoreeri dokumente. Mälu on eraldatud dokumentide stringide jaoks. Kommentaar on koodi kirjeldus, kuid teisest küljest näitavad dokumendistringid meile koodi eesmärki.
Süntaks:
NumPy dokumendistringide kirjutamise süntaks on:
'''Dokumendistringi sõnum'''
Või
'''Docstring sõnum'''
Pange tähele, et dokstring ei ole funktsioon ega meetod, seega pole sellel õiget süntaksit. Ainus asi, mida siinkohal märkida, on see, et me alustame dokumenti kolme üksikjutumärgiga või kolme topeltjutumärgiga. Kirjutame oma koodi kirjelduse ja lõpetame selle uuesti kolme üksikjutumärgiga või kolme topeltjutumärgiga. Dockstringide jaoks pole kohustuslikku asja kirjutada. Peate lihtsalt panema kolm ühe- või topeltjutumärki enne ja pärast stringi kirjeldust.
Näide 1:
Dokumendist paremaks mõistmiseks toome näite. Selles näites deklareerime pärast NumPy teegi lisamist lihtsalt muutuja 'a' ja teise muutuja 'b'. Pärast seda loome oma dokumendistringi, mis ütleb 'Lisagem 'a' ja 'b' muutujad'. Meie puhul on see lihtne näide, kuid kui meie kood on keeruline, aitab see kodeerijal palju koodi mõista. Pärast seda liidame muutujad “a” ja “b” ning salvestame nende väljundtulemuse teise muutujasse, milleks on “c”. Lõpuks trükime muutuja “c” väärtuse. Nüüd käivitame oma koodi.
importida tuim nagu nt.a = 1
b = kaks
''''Lisame a ja b muutujad'''
c = a+b
printida ( c )
See on meie väljund antud koodiosast. Näeme, et süsteem ei ole meie koodi rea 7 jaoks andnud ühtegi viga vale süntaksi ega midagi. Samuti pole süsteem meie dokumenti trükkinud. Selle asemel printis see ainult meie muutuja 'c' väljundi, milles kästisime oma süsteemil printida. See näitab, kuidas dokumendistringid töötavad. Järgmine kord, kui uus kodeerija proovib meie koodi kallal töötada, saab ta oma dokumendistringi abil aru, mida me teeme. Kuid seda ei trükita väljundina, nii et see ei häiri koodi kasutajat.
Näide 2:
Nüüd esitame keeruka näite, et mõista dokstringi toimimist. Esiteks lisame NumPy teegi ja seejärel kirjutame dokumendistringi, milles selgitame järgmist koodirida, kus selgitame massiivi lähtestamist. Lisame ka dokstringid koodi teises osas. Kui me nüüd jagame seda koodi mõne uue Pythoni arendajaga ilma dokstringe lisamata, on tal kuidagi raske teada selle koodi toimimist ja eesmärki. Ta peab kõigepealt otsima meie kasutatud funktsioone. Kuid kui lisame oma koodile dokumendistringi, on teistel arendajatel lihtne koodi mõista, ilma funktsioone lähemalt uurimata. Me ei piirdu kommentaaride lisamisega teatud piiridesse; kommentaarid võivad koosneda ühest või mitmest reast. Selle saab koodi lisada ka mitu korda. Seejärel importige NumPy np-na.
''''Muutuja loomine, millele edastame massiivi suurusega 1x6'''massiivi = nt. massiivi ( [ üksteist , 22 , 33 , 44 , 55 , 66 ] )
''''massiivi määramine funktsioonile tofile(), et lasta see salvestada faili nimega arr'''
massiivi . viilima ( 'arr.bin' )
''kuva faili funktsiooni fromfile abil'''
printida ( nt. failist ( 'arr.bin' , dtüüp = int ) )
Nagu on näidatud järgmises katkendis, ei kuvata väljundis dokumente, mis tähendab, et see ei mõjuta koodi väljundit ega kompileerimist. Dokumendistringe eiratakse koostamise käigus.
Järeldus
Sellest juhendist õppisime NumPy dokstringide kohta. Võrdlesime dokumente kommentaaridega ja selgitasime nende mõlema erinevust. Õppisime dokstringide süntaksit ja dokstringide koodi kirjutamist. Lisaks proovisime näidete abil selgitada, mis on NumPy dokstringid ja kuidas need töötavad. Lõpuks märkisime, et need on kodeerijate jaoks hädavajalikud. Me ei korda NumPy dokumentide tähtsust. Ütleme lihtsalt, et peaksite kasutama oma koodis olevaid dokumente. NumPys on dokumentide kirjutamisstiil kõige populaarsem. Seda kasutatakse programmeerimiskogukonnas laialdaselt, et anda üksteisele teada oma koodide toimimisest ja funktsionaalsusest. See juhend aitab teil NumPy dokumendistringidega alustada. Püüdsime NumPy dokumentide stringide abil katta suurema osa sellest, mida vajate.