Jezik na kome pišete komentare i imena promjenljivih?

Programski jezik jeste jezik ali ljudi nisu kompjuteri. Programski jezici prenose instrukcije, prirodni jezik moze da prenosi i instrukcije i razumevanje koristeci nasu urodjenu sposobnost komunikacije i vizuelizacije. Trece, ljudi imaju razlicite stepene predznanja i razlicite nacine razmisljanja i resavanja problema i sposobnost ekstrapolacije znacenja iz koda nije univerzalna. Tebi se mozda cini da 0.5% koda treba dokumentovati ali za nekog je potrebno dokumentovati mnogo vise, za nekog treceg je potrebno dokumentovati 0.2% koda koji tebi izgledaju kao da su trivijalni (kao sto bi njemu tvojih 0.5% izgledalo trivijalno). Zato se takve stvari ne ostavljaju slucaju i postoji nekoliko nivao dokumentacije koja ide uz projekt, zavrsno sa komentarima koda.

Potpis

Sloba je za 12 godina promenio antropološki kod srpskog naroda. On je od jednog
naroda koji je bio veseo, pomalo površan, od jednog naroda koji je bio znatiželjan, koji
je voleo da vidi, da putuje, da upozna,
od naroda koji je bio kosmopolitski napravio narod koji je namršten, mrzovoljan,
sumnjicav, zaplašen, narod koji se stalno nešto žali, kome je stalno neko kriv - Z.Đinđić

Vi ljudi protiv komentara - jer radite vi kao programeri u nekom timu ili su to čista teorijska naklapanja?

Jer mislite da su softverske firme pale sa marsa kada sve do jedne promovišu komentare? Mislite da kada bi to bilo efikasnije - da se ne bi našla jedna velika firma koja bi rekla - vrijeme naših programera možemo pametnije iskoristiti - i zbog toga - nema komentarisanja kod nas? I svoju filozofiju dokazala većom produktivnošću programera?

Ajde navedite mi ijedan primjer iole ozbiljnog projekta koji nije komentarisan?

Naravno da ako pravim neku glupu aplikaciju od par klasa koju sam sklepam od danas za sutra- da ne moram da komentarišem - ali pravi projekti - a ovdje o tome pričamo moraju imati komentare jer će te kasnije svaki ušteženi sekund koštati dane.

@nedeljko - pričaš gluposti. I mašinski jezik je "jezik" pa ne vidim da ga ljudi tako lako tumače - baš bih volio da vidim nekog ko kao u matrixu proleće kroz heksa zapis mašinskog jezika i vidi pametne strukture petlji, uslova i slično ;)

Viši jezici su lakši i bliži prirodnima - ali i dalje to nije to...

P.S. Sledeći vašu logiku - logika je ista ako se promjenljiva zove winningNumber ili w, a ovo drugo je brže za kucanje - ili metod b(), ha ha ha - baš bih volio vidjeti neki takav kod - nisam odavno ;)

Najlepsa varijanta jeste da sve funkcije vracaju samo true ili false..onda tu nista ne treba komentarisati, samo zapamtiti imena funkcija. A koja cemu sluzi, trebalo bi se znati. Ako se to ne zna, onda dzaba i komentari.
A komentare ubacivati tamo gde je prekid kod-a, gde se pozivaju drugi fajlovi, klase... Mnogo su korisniji komentari koji opisuju strukturu aplikacije nego oni koji opisuju samo posao koji radi neki kod.

Trebalo bi se znati? A kako si zamislio da se to zna?

Potpis

www.yanado.com
www.startupscave.com
www.e-75.rs
www.twitter.com/mojsilo_

E, pa, nije sve relativno. Ako sam primenio bilo kakvo nestandardno rešenje, dužan sam da ga dokumentujem nezavisno od "trivijalnosti. Za standardne stvari (a to je 99,5% koda), aman. Čemu dokumentacija?

E, pa vidiš. Naravno da promenljivu treba nazvati winningNumber. Kada je tako nazoveš, onda je jasno čemu služi i čemu onda još i komentar? Svojim nazivom je već dokumentovana.

I da, znam nza više softverskih firmi sa velikim projektima koji nisu dokumentovani.

@mmix

Ovde ti je odgovor na konstataciju da ljudi nisu kompjuteri - zato se identifikatori pišu na prirodnom jeziku. To je taj kompromis.

Potpis

Nije bitno koji su zaključci izvučeni, već kako se do njih došlo.

E, to bih vodeo da mi neko dokaže, da ćeš ulaganjem vremena A u dokumentovanje više od 1% koda kasnije uštedeti vreme B koristeći kod određen broj puta čije je matematičko očekivanje N, tako da bude A<NB.

Potpis

Nije bitno koji su zaključci izvučeni, već kako se do njih došlo.

Nisam racunao ali tamo gde sam imamo komentare znao odmah na koje klsae i servise treba da obratim paznju, a tamo gde ih nije bilo gledao sam kod da bihprovalio. Nasledio sam projekat posle 10 godina.

Potpis

www.yanado.com
www.startupscave.com
www.e-75.rs
www.twitter.com/mojsilo_

OK, koliko ti je trebalo da se ukačiš u nedokumentovan kod, a koliko je bilo potrebno da se napiše dokumentacija za 100% koda?

Opet, da je bilo onih 0,5% dokumentacije, da li bi onda znao koje klase da gledaš?

Koliko treba pisati da bi znao koje klase da gledaš? Rekao bih jedan kraći word fajl za veliki projekat.

Znam ja da je teško napustiti uvrežena shvatanja, ali pokušajte da merite stvari i da ih upoređujete bez predrasuda.

Potpis

Nije bitno koji su zaključci izvučeni, već kako se do njih došlo.

Pa ako bi sistem bio tako napravljen, kao sto sam rekao, da funkcije vracaju samo true i false, onda bi te funkcije bile, morale da budu jednostavne. Provera da li email postoji u bazi, da li korisnik logovan, da li je registrovan itd...sve su to proste funkcije cije se znacenje vidi odmah iz koda a isto iz imena funkcije.
Ali, sta ja tu pricam, pa ja i nisam pravi programer, a mislim da nije ni nedeljko... :)

Ako su za razumevanje dela koda dovoljni kod i opšta znanja iz struke, onda ga svakako ne treba dokumentovati, jer čak i ako neko nema neko opšte znanje, pitaće nekoga ko ga ima - to nije vezano za projekat.

Ako kod sadrži nešto nestandardno, tj. za razumevanje nisu dovoljna opšta znanja iz struke, onda to svakako treba dokumentovati.

Tako se dolazi do onih 0,5%. Preostalih 99,5% dokumentacije su dobro izabrana imena identifikatora, fajlova i projekata.

Potpis

Nije bitno koji su zaključci izvučeni, već kako se do njih došlo.

Ja sam sve vreme mislio na php..a tek sad vidim da je ovo forum Art of Programming. Tako da, ups. Treba da postoje komentari :D

Da, vrlo zanimljiva diskusija. Mislim da realno stvari stoje ovako. Source treba da sadrzi komentare, opsirne u zavisnosti od strukture tima, ideje, namene, proširivosti, projekta itd.. A da li taj source posle prosledjivati dalje, pa to zavisi valjda od licence i opet od volje programera. Naravno da je za krajnji rezultat (za korisnika) najbitnije da je program brz i ispravan a to opet postavlja pitanje postojanja komentara. Tako da eto jeste da ne razumem baš najbolje javascript, ali mi ses vidja sto su zbili onako kod. A usput ima i source...

A ja govorim pre svega o velikim, ozbiljnim, profesionalnim projektima.

Potpis

Nije bitno koji su zaključci izvučeni, već kako se do njih došlo.

Ja stvarno ne znam o kojim projektima ti pricas, ali u mom svetu ta tvoja prica ne pije ni malo vode. Mozda sam ja subjektivan jer da prica ide kako ti kazes ja ne bih imao 80% svojih radnih obaveza ali mene bi cak bilo sramota da dam ponudu za projekat a da isti nema dokumentaciju. Al nemam ni potrebe za time jer je jedan od projektinih zahteva UVEK izrada dokumentacije od koje gro bude izradjen pre nego se uradi i linija koda. Sta vise, neka dokumentacija se pise na razlicite nacine za ISTU stvar, jedna verzija arhitekture sistema ide u risk managment grupu, druga u PM za project tracking, treca u IT board za approval i akviziciju opreme i softvera, itd. Developeri ne vide skoro nista od toga dok projekat ne dodje do nekih 30% zavrsetka i izlaze iz price na nekih 80% nakon cega ide UAT, treninzi, project closure, itd. Pravi se dvonedeljni presek i projekat je uvek up-to-date i dokumentovan do te mere da kompletan dev moze da se pauzira, stornira, cak i prebaci u potpuno novu ekipu. Ne ide to tako vise bre da ti sednes i iskucas program i svi srecni I prosla su vremena kad su devovi kontrolisali tok projekta scrumm je bezobrazni pokusaj da se to ponovo aktivira kroz agile ali znamo i mi za jadac

Potpis

Sloba je za 12 godina promenio antropološki kod srpskog naroda. On je od jednog
naroda koji je bio veseo, pomalo površan, od jednog naroda koji je bio znatiželjan, koji
je voleo da vidi, da putuje, da upozna,
od naroda koji je bio kosmopolitski napravio narod koji je namršten, mrzovoljan,
sumnjicav, zaplašen, narod koji se stalno nešto žali, kome je stalno neko kriv - Z.Đinđić

Evo, ko na primer radi sve bez dokumentacije:

www.arahne.si
www.investintech.com
www.teletrader.com

Budi siguran da nisu jedini, a uspešne su firme u pitanju.

Investintech je čak prebacivao nedokumentovane projekte sa novim ljudima sa MFC-a na Qt (pa čak i sa C++ MFC-a na C#). I? Ništa! Transfer complete.

Potpis

Nije bitno koji su zaključci izvučeni, već kako se do njih došlo.

Dobro sad - moj ideal je nešto izmedju nedeljka i mmix. Sa jedne strane - nešto mora unapred biti definisano i dokumentovano uz male izmjene poslije (npr. komunikacija - XML specifikacija i sl), ali mi je suludo da za cijeli projekat spremam ogromnu dokumentaciju i pre nego počnem i tu mi je sasvim uredu agile.

U samom kodu dokumentacija mi je uglavnom - svako public/protected polje i metod po jedan javadoc stub koji se proširuje ukoliko se radi o nečemu netrivijalnom - plus tamo gdje mislim da treba - sveukupno - možda 10% koda je dokumentacija. Ovih 0.5% mi se čini baš mnogo malo... I tih 10% mi oduzima možda 5% dodatnog vremena - a s obzirom da se trudim da dokumentujem metod nakon što ga iskodiram (naravno ima izuzetaka kada imam ideju za više povezanih metoda pa sve u jednom dahu završim) i to mi dodje kao dobro vrijeme da rezimiram šta sam uradio. I često dok pišem komentar uvidim da bi to moglo bolje uz neku sitnu optimizaciju.

Ne znam da li znate za onu aksiomu da u principu mnogo više naučiš kada neko gradivo predaješ drugima - nego kada ga samo učiš. Na sličan način mi pisanje komentara pomaže da sagledam moj kod i steknem bolji utisak kako sve zajedno funkcioniše. Tako da to i zbog toga ne smatram izgubljenim vremenom. Nismo mi programeri mašine koje izbacuju određeni broj linija koda po minuti - pa je samo pitanje koliko će od toga biti komentari, da bi toliko bila bitna ta "produktivnost".

Ja sam sa mmix-om i Ivanom 100% mada znam i za ove kao sto je Nedeljko, sta vise trenutno radim u takvom okruzenju gde se forsira scrum bez ikakve dokumentacije neracunajuci video tutorijale za end usere. 3.5 godine sam radio tako sto sve mora da se dokumentuje na vise nivoa bukvalno ovako kako je mmix opisao i navikao sam kad preuzimam nesto da radim prvo gledam dokumentaciju. Samim tim najezim se kad dodjem u tim i glavni baja mi samo otvori solution i kaze teraj, a packe sam dobio kad sam dokumentovao prvi feature koji sam radio uz obrazlozenje "kod je najbolja dokumentacija, a UML je za slabice" :)

A jeste li vi čuli za aktivnu dokumentaciju? Hint: test driven development.

Potpis

Nije bitno koji su zaključci izvučeni, već kako se do njih došlo.

Ma sve je to super dok oni piske u svom dvoristu i niko ih ne pita za nista, a onda kad pocne interakcija sa ozbiljnim klijentima onda svi u timu peru ruke i daju jednoglasan odgovor "to je odnos sa klijentom, to radi product manager" i tako dobijes paradoksalnu situaciju da product manager koji veze nema sa time mora da pise tehnicku dokumentaciju za klijenta, pa mozes misliti nasta to lici na kraju i koliko je "tehnicka" ta dokumentacija. Ceo taj scrum je made by devs, for the devs i kao takav je potpuno nakaradan u svetu s/w biznisa gde je prioritet obrt kapitala a ne izbegavanja dosadnih poslova.

Potpis

Sloba je za 12 godina promenio antropološki kod srpskog naroda. On je od jednog
naroda koji je bio veseo, pomalo površan, od jednog naroda koji je bio znatiželjan, koji
je voleo da vidi, da putuje, da upozna,
od naroda koji je bio kosmopolitski napravio narod koji je namršten, mrzovoljan,
sumnjicav, zaplašen, narod koji se stalno nešto žali, kome je stalno neko kriv - Z.Đinđić

Nemam ja nista protiv da se testovi pisu pre kodiranja funkcionalnosti pa da kroz iteracije fail-success dodjes do cilja, ali imam protiv toga da se to koristi kao jedina dokumentacija.

Taj skram primenjuju i MS i Google i Yahoo, ali ne, oni ne znaju da obrću kapital ili im to nije prioritet.

Ako dokumentacija treba da se radi za klijenta, OK. Onda mu se lepo izračuna koliko košta postojeći projekat u postojećem stanju, a koliko dokumentovanje, pa neka sam odluči. Neću ja da ga učim šta njemu treba (čitaj "da ga pravim budalom"). Ako on odluči da mu se isplati da plati dokumentovanje, nema problema, ali to onda više nije tehnička dokumentacija, već finalni proizvod.

A čemu služi preostala dokumentacija?

Potpis

Nije bitno koji su zaključci izvučeni, već kako se do njih došlo.