Unosi za: Arhiva za 2006/09
Najlakši put do relativno kvalitetne i sveže dokumentacije je korišćenjem pravilno formatiranih komentara unutar samog koda. Dokumentacija može biti up-to-date bez mnogo cimanja samo uz malo discipline pošto je uvek programeru pred očima i lako ju je lako održavati.
Primer jednog takvog inline komenatara za PHP:
/** * Check if specific page is first page * * @param integer $page Page that need to be checked. If * value of this param is NULL current page will be used * @return boolean */ function isFirst($page = null) { $page = is_null($page) ? $this->getCurrentPage() : (integer) $page; return $page == 1; } // isFirst
Jednostavno. Sve ide samo od sebe kad se nauči par pravila i stekne navika pisanja ovakvih kometnara (ako koristite neki napredniji editor koji podržava code template onda editor može da odradi skoro sav dosadan posao za vas).
Ovako spremljena dokumentacija se pomoću specijalizovanih alata lako prebacuje u čitam i ulinkovan oblik. Standardan alat za izvlačenje dokumentacije iz PHP koda je phpDocumentor, a ako vas zanima kako izgleda generisana dokumentacija na ovoj stranici imate gomile linkova ka dokumentcijama "živih" PHP projekata koje su generisanje pomoću ovog alata.
Sve je to jako lepo, ali meni smeta par stvari. Prva i osnovna je što uz phpDocumentor ne dolazi ni jedan set templatea za koji se može reći da je dovoljno jednostavan i čitak da bi ljudi stvarno čitali generisanu dokumentaciju. Sve mi deluje previše nabacano, a developeri kao da su se trudili da akcentuju nebitne stvari. Dokumentacija je maksimalno nepregledna, prostor loše iskorišćen, a podaci koji su prikazani su u prevelikom broju slučajeva jednostavno nebitni i smetaju čoveku da dođe do stvarno vrednih informacija.
Primer čitke i pregledne API dokumentacije izvučene iz koda možete videti kod Rails API dokumetnacije. Vidi se da je u istu uloženo dosta truda, a sam layout dokumentacije je dovoljno pregledan (ako izuzetmo gomile frameova sa strane, to je moglo mnogo lepše da se reši).
No dobro, na svu sreću phpDocumentor podržava definisanje custom seta template (opet malo nesrećan način definisanja tempaltea) tako da ću najverovatnije sesti i napraviti sopstvene kad bude bilo potrebe da generisane dokumentacije i javno pokažem.
[urke@urosevic ~]$ /opt/bin/amsn
Error in startup script: unknown color name "white"
(processing "-background" option)
invoked from within
"text $window.info -background white -width 60 -height 30 -wrap word -yscrollcommand "$window.ys set""
(procedure "::pluginslog::draw" line 10)
invoked from within
"::pluginslog::draw"
invoked from within
"if { $initialize_amsn == 1 } {
::pluginslog::draw
}"
(file "pluginslog.tcl" line 205)
invoked from within
"source pluginslog.tcl"
("uplevel" body line 22)
invoked from within
"uplevel \#0 {
source ctthemes.tcl
source progressbar.tcl ;# Progressbar Megawidget
source migmd5.tcl
source des.tcl ;# DES encryption
source s..."
(procedure "reload_files" line 2)
invoked from within
"reload_files"
(file "/opt/bin/amsn" line 224)
Hmmmm... zbunj! Grеmlini, zаšto vаs jе čikа Mаrfi bаš sаdа poslаo kod mеnе?!
Prvа loptа - zеznulа jе nеkа nаdogrаdnjа nеkog od pаkеtа koju sаm rаdio yum-om protеklih dаnа (pošto aMSN nisаm pаlio nеkoliko dаnа unаzаd). Skinеm i originаlnе FC5 Tcl/Tk i aMSN pаkеtе, skinеm i mojе pаkеtе, ponovo ih rеkompаjlirаm i nаprаvim novi sеt, instаlirаm, pokrеnеm, opеt istа grеškа. Pomislim, moždа jе do vеrzijе 0.96RC1 aMSN-а, pа kompаjlirаm vеrziju 0.95, аli isti đаvo. Smаrаo sе i prijаtеlj Igor sа mnom oko ovogа, dаvаo mi prеdlogе štа dа probаm i kаko dа otkrijеmo bubu, аli ništа. aMSN sе nе dа zbuniti.
A dobro, postаvim dobro koncipirаno pitаnjе mom drugаru Guglu i on mi u sеtu odgovorа ponudi i onаj prаvi.
EVO REŠENjA! Prе nеkoliko dаnа, kаd sаm nа brzinu štеlovаo TV izlаz u xorg.conf-u, ubаcim i liniju:
http://www.google.com/
Nа aMSN forumu pronаđеm odgovor nа pitаnjе kojе sе odnosilo nа problеm sličаn momе, i ispostаvi sе dа jе tа linijа onа kojа prаvi pomеtnju. Zаkomеntаrišеm jе, rеstаrtujеm X sеrvеr, pokrеnеm aMSN, et voila! Rаdi!
Stepen imbecilnosti nase televizije je ENORMAN!!! Na javnom servisu se citira Z.Cirjakovic kao relevantan izvor bilo cega (za one koji ne znaju doticnog gospodina, mozete na http://www.zamislisrbiju.org/forum/viewforum.php4?f=80 procitati tekst velikog arhi-gurua slobodarske misli gospodina Petra Lukovica o doticnom elementu); za to vreme, na tv kosavi (koja je, ne zaboravimo, dobila "nacionalnu" frequenciju ma sta to znacilo) se prica o tome kako postoje arheoloski nalazi da se dinja (da, da - dinja) koristila jos 3000 godina pre Hrista. Who gives a fuck???. Ludilo, brate! Booggie wonderland all over.
Pored gorenavedenog, moj danasnji dan bi se najlakse mogao opisati kroz metaforu - baterija sa dva pola, plus i minus, svaki nakacen tamo gde treba. Dakle, danas sam emitovala i primala i pozitivnu i negativnu energiju, a to sam shvatila veceras na stolu za masazu dok je iza paravana na domak mene lezala neka mentalna spodoba koja je jako jako dugo pricala, a to se u spa ne radi, jer tamo dodjes da te masiraju a ne da pricas maserki kako si pravila neki "event" u hyattu i kako te sad bole ledja jer si morala da razmisljas i o svetlu i o bini i o manekenkama i da sutra putujes u grcku i bla bla bla!!!! Kad o tome hoces da pricas odes lepo kod Mace u blokove za 300 kinti i pustis svoju seljacku dusu na pasnjak domacinskog raspolozenja. I tako, kazem ja sebi, daj nemoj se nervirat' jebiga, ona te zraci negativno al imala si i ti danas svoju epizodu. Sto jes, jes - imala sam. Udjem ja danas u Zaru da nadjem nesto sto ne kosta 200 ili 300 evra a sto mogu da obucem na vece tog spektakla u petak u Parizu. Milsim, sta ja da obucem tamo? Necu da kupujem neku "balsku" haljinu posto to nije matura a necu ni da izgledam kao prokleti istocni evropljanin i tako obidjem Zaru, omiljeno steciste svih i svjah, a nadasve vlasnica fake Louis Vuiton tasni. I takav jedan primerak, naravno, preko reda pokusa da zameni neko govno koje je prethodno pazarila. I sad, nije sto je ova pokusala nego sto prodavacica to olako prihvati i kaze meni posle par minuta "mozete da predjete u drugi red". Ja kazem "moi? pa vi mora da se salite" i ona tu mene kao izignorise, sto kapirate i nije bio bas the smartest move. Jos kaze "znate, to je, generalno, sve jedan isti red". Ja kazem "ajte vi, generalno, da pozovete menadzera". Epilog price - manager muskog odeljenja se pojavljuje, ja ga pitam, what the fuck? jel sam ja na muskom odeljenju? onda stize neka cica koja izgleda kao da je krenula da kupi sladoled sa sve tasnicom preko ramena i kaze ona je menadzer cele radnje. cele radnje? no shit. elem, tu sam ja imala par minuta teskog pizdenja sa sve zahtevom da vidim pravilnik u kome pise da se zamene uzimaju u obradu pre naplate novih proizvoda (!?!) Na kraju ja je pitam, dobro, ako ja napisem tu zalbu sta ce se desiti. Ona kaze, pa ta devojka (ova sto je generalno tu mene zajebavala) ce dobiti opomenu pred otkaz, ja kazem dobro dajte mi mail i odem. Posle razmisljam, necu da dobije otkaz, u krajnjoj liniji docice ista takva koja ce mozda biti jos veci idiot. Nekako mi zao. Mozda gresim. Dobra dusa, sta ces. Mada kad bi mi se ista prilika ukazala vezano za neku od onih skotusa na salteru Hypo banke, mozda ne bih bila tako empaticna.
Ali ali ali! Ako ste mislili da je sve negativno - nije. Imala sam i momenat sirenja i primanja pozitivne enregije, ali to ni upola nije jednostavno predstaviti na svima zanimljiv nacin kao gore opisane dogadjaje. Recimo samo da je mene jedan e-mail jutros izuzetno oraspolozio te da su nekome narandzaste ruze ulepsale dan, a znamo da nema lepseg poklona od toga kad vidis da se prijatelj iskreno necemu obraduje ili odusevi.
Apple je od jednog sjajnog proizvoda napravio novi, potpuno bezvezan. Stari Shuffle je sjajna, modularna sprava. Direktan USB priključak je omogućavao da se lako koristi kao flash drive, a da se time ništa nije gubilo na strani MP3 playera. Ta mobilnost je i više nego nadoknađivala nedostatak bilo kakvog ekrana.
Novi Shuffle umesto USB priključka ima USB dock, koji je daleko nezgodniji za nošenje, čak bih rekao potpuno neupotrebljiv. A pritom i dalje nema nikakav ekran i glavni novi feature je zakačka za pantalone. Wow. Najbolji mali MP3 flash player su pretvorili u jedan od najgorih.
Ne znam tačno čime bih opisao ovakav “upgrade”, a da dovoljno jako prenese moju zgađenost.
Apple je od jednog sjajnog proizvoda napravio novi, potpuno bezvezan. Stari Shuffle je sjajna, modularna sprava. Direktan USB priključak je omogućavao da se lako koristi kao flash drive, a da se time ništa nije gubilo na strani MP3 playera. Ta mobilnost je i više nego nadoknađivala nedostatak bilo kakvog ekrana.
Novi Shuffle umesto USB priključka ima USB dock, koji je daleko nezgodniji za nošenje, čak bih rekao potpuno neupotrebljiv. A pritom i dalje nema nikakav ekran i glavni novi feature je zakačka za pantalone. Wow. Najbolji mali MP3 flash player su pretvorili u jedan od najgorih.
Ne znam tačno čime bih opisao ovakav “upgrade”, a da dovoljno jako prenese moju zgađenost.
- Filter unosa
- Arhiva
- Blogodak
Blogodak?
Blogodak je vaš pogled na domaću blogosferu. Prijavite se i napravite sopstvenu listu blogova koje pratite.
Podrška
