DocStrings (stringovi koji služe kao dokumentacija našeg programa)

9.9 DocStrings (stringovi koji služe kao dokumentacija našeg programa) 

Do sada, ako si želeo da dodatno objasniš neke stvari u programu si koristio komentare. Za komentare smo rekli da ih Python ne prepoznaje, tj da ih ignoriše. Ali sa pojavom potrebe da se neki delovi programa ponavljaju u samom tom programu, ili čak u nekom drugom, komentari nisu dovoljni, zar ne? Kada bi nam komentari bili jedina mogućnost, ako bi smo želeli da znamo šta nam radi funkcija tipa len(), mi bi smo morali da nađemo njen kod, otvorimo ga, nađemo komentare i potom ih pročitamo! Prilično nepraktično, zar ne?
Python nam priskače u pomoć i u ovakvom slučaju, jer ima jednu divnu funkcionalnost, koja bi se mogla nazvati dokumentacioni string, ili svojim engleskim imenom DocStrings. DocStrings je važno sredstvo koje bi trebalo da koristiš kada god možeš, i gde god možeš.Služi nam da bolje dokumentujemo program i može da ga učini lakše razumljivim. Zapravo, mi možemo da pristupamo DocStrings-ima direktno iz našeg programa!
Kako to u stvari funkcioniše i izgleda?
>>> def kredit(*suma, minus): 
...     '''Funkcija koja nam vraća zbir vrednosti u sumi 
...     ukoliko nam je dozvoljen minus. 
...     Vrednost minus mora biti prosleđena funkciji kao ključna reč!''' 
...     c = 0 
...     for i in suma: 
...             c += i 
...     if minus: 
...             return c 
...     else: 
...             return 'Nije dozvoljen minus!' 
... 
>>> kredit(1000, 120, 125.588, 58887, -75858, minus = False) 
'Nije dozvoljen minus!' 
>>> 
Definisali smo funkciju kao i mnogo puta do sada, i ona radi onako kako je i očekivano. Novost je višeredni string definisan između trostrukih navodnika ili apostrofa odmah ispod definisanja naziva funkcije. Taj string je DocString za tu funkciju.
Konvencija koja prate programeri je da je DocString string iz više linija, u kojem se objašnjava šta će se dobiti od te funkcije, i šta koji parametar znači. Tj „pogled“ u DocString nam je sasvim dovoljan da znamo šta ta funkcija radi, a kako radi – više nam i nije važno, jer znamo šta od nje očekujemo. Zapamti da se DocStrings mogu definisati i unutar modula i klasa, koje ću ti pokazati u nekim narednim delovima ovog tutorijala. 
Ali, ja i dalje moram da čitam program... Ovo sam isto mogao da postignem i sa komentarima...
Zapravo, ne! Upravo ću ti pokazati moć DocStringa! Gledaj magiju:
>>> print(kredit.__doc__) 
Funkcija koja nam vraća zbir vrednosti u sumi 
 ukoliko nam je dozvoljen minus. 
 Vrednost minus mora biti prosleđena funkciji kao ključna reč! 
>>> 
Vidiš da jednostavno možemo pristupiti DocString-u naše kredit funkcije koristeći __doc__ (napisano je kao dve donje crte, zatim reč doc, a potom opet dve donje crte) atribut naše funkcije. I slično tome, na isti način možemo da vidimo i bilo koji definisani DocString bilo koje funkcije!
>>> print(print.__doc__) 
print(value, ..., sep=' ', end='\n', file=sys.stdout) 

Prints the values to a stream, or to sys.stdout by default. 
Optional keyword arguments: 
file: a file-like object (stream); defaults to the current sys.stdout. 
sep:  string inserted between values, default a space. 
end:  string appended after the last value, default a newline. 
>>> 
Mnogi editori i IDE-i poseduju automatizovane funkcionalnosti koje prikazuju dokumentaciju u toku pisanja programa na način sličan opisanom. Jednostavno, pišući poziv neke funkcije će ti iskočiti prozorčić koji objašnjava šta ta funkcija radi! Zato je jako preporučljivo da koristiš DocStrings za sve funkcije koje definišeš.
Ako si me poslušao i dosta koristio funkciju help() , sledi iznenađenje – ti si, u stvari koristio DocStrings-e! Ono što help() funkcija radi je da samo iščita  __doc__ atribut traženog objekta, a zatim ga lepo prikaže. Evo i dokaz:
>>> help(kredit) 
Help on function kredit in module __main__: 

kredit(*suma, minus) 
    Funkcija koja nam vraća zbir vrednosti u sumi 
    ukoliko nam je dozvoljen minus. 
    Vrednost minus mora biti prosleđena funkciji kao ključna reč! 
(END) 
Ne zaboravi da je izlaz iz help režima taster q. 
Postoji i pydoc komanda, koja na tvoj sistem dolazi prilikom instalacije Python-a, a koja radi slično help() funkciji jer koristi DocStings, ali ova komanda se ne pokreće iz Pythona, već je zasebna komanda u operativnom sistemu. Ona iz DocStringsa generiše HTML dokumente koje kasnije možeš da pregledaš u web pregledaču. Za više informacija, u Python interaktivnom promptu probaj:
>>> help('pydoc')

9.8 Naredba return Indeks 9.10 Rezime

Primjedbe

Popularno ovog meseca

Gde pronaći novosti sa facebook stranica nakon velike promene koja ga je zadesila?

Dva načina da vratite svoj Windows 10 na fabričke vrednosti

Kako preuzeti video koji je neko postavio na facebook-u bez upotrebe dodatnih programa?

Više neće biti moguć besplatan prelazak na Windows 10

Prijateljski meč ŠK "Titel" - ŠK "Bukovac"

Tu je novi Qt creator 4.4.0!

Kako manipulisati Windows licencom pomoću slmgr komande?

Fake poet

Da li je poželjno biti anoniman na internetu (ili se predstavljati punim imenom i prezimenom)?

Organizacija foldera i fajlova u Linux fajl sistemu