PHP funkciju komentāri

[daGrevis]

> Nav jau jēga paskaidrot, ko tur dara ( parasti; jo primāri tas, ko dara, jau ir uzrakstīts kodā ), bet gan KĀPĒC dara: "$var += 1; // by the will of unknown forces and our Lord Satan, the laws of physics states that correct gravitational forces' calculations require $var to be incremented by one, Bible of Satan 6:66".

 

+1

[spainis]

Bob Martin - Clean Code( http://www.bookdepository.co.uk/Clean-Code-Robert-Martin/9780132350884 )

[codez]

Funckijās ir jāpasakidro arī ko tās dara, jo ne vienmēr funkcijas nosaukums precīzi pasaka, ko funkcija tieši dara, tāpat funkcijas nosaukumā diez vai būs pateikts kādi parametri jānodot kādā formā un ko funkcija atgriež.

 

Piemēram, ja funkcija saņem par parametru sarakstu ar ID vērtībām, piemēram tā būs funkcija, kas nosūta kaut kādu ziņojumu, tad parametra aprakstā jāpaskaidro, ka, piemēram, id nodod kā string-u ar atsarpēm "1 4 8 19 25" vai kā stringu ar komatiem "1,4,8,19,25" vai kā PHP array array(1,4,8,19,25), vai arī ka funkcija saprot visus formātus. Tālāk nosūtāmā ziņa it kā varētu būt strings, bet arī tai kā parametram var norādīt nianses, piemēram, ka tā tiek eskeipota funkcijā.

 

/**

*  Nosūtīt ziņu lietotājiem pēc to id.
*  
*  @param array|string $ids Lietotāju id, kuriem sūtīt ziņu. PHP array vai strings ar atstarpēm starp id "1 5 9 12".
*  @param string $message Lietotājiem nosūtāmā ziņa, nav jāeskeipo pret xss, to dara funkcija.
*/

function sendMessage($ids,$message){
}

 

Šādi nodokomentēta funkcija IDEē arī parādīs visus parametrus, kas jāraksta un uzreiz redzēsi katram parametram īsu aprakstu. Tā vietā, lai darbinātu ilgtermiņa atmiņu visu šo lietu atcerēšanai, var koncentrēties un pašas aplikācijas izstrādi un ļaut IDEi un dokumentācijai būt kā daļai no savas atmiņas.

 

 

Vēl viens piemērs būtu arī ar atgriezstajām vērtībām:

Piemēram, ir klase db un db result. db klasē ir metode query, kura atrgriež dbresult klasi, kurai ir daudz metodes, ko un kā darīt ar rezultātu

 

class db{
 /**
 * Izpilda db pieprasījumu un atgriež rezultātu kā dbresult klasi.
 * Kverijā var izmantot %s, lai automātiski ievietotu eskeipotus parametrus, kurus nodod šijā pašā metodē aiz kverija.
 * db::query("SELECT * FROM user WHERE group=%s AND gender=%s",$groupid,$gender)->...
 *
 * @param string $querystring Kverijs
 * @param mixed $attr,...  papildus parametri, kurus eskeipot un ievietot kverijā.
 * @return dbresult kverija izpildes rezultāts
 */
 static function query($querystring){
 }
}

class dbresult{
 /**
 *  Atgriež vienu ierakstu
 *  @return array associatīvs 1D masīvs ar viena ieraksta datiem
 */
 function row(){
 }
 /**
 * Atgriež visus rezultāta ierakstus
 *  @return array 2D masīvs ar visiem ierakstiem
 */
 function rows(){
 }

 function json(){}
 function one(){}
 ...
}

 

Tālāk, ja man ir šādi dokumentēts kods, tad, rakstot IDE, es uzrakstu db:: un man jau parāda visas db metodes ar aprakstiem.

Ja tālāk es izvēlos db::query, es uzreiz IDE papildus logā redzu, kādi parametri jānodod un to aprakstus, redzu īsu piemēru kā šo funkcju izmantot.

Ja tālāk uzrakstu db::quert("SELECT ....")-> tad tagad IDE man atver izvēlni ar visām pieejamām dbresult metodēm (one, row, rows, json, utt.) un viņu īsiem aprakstiem.

Labi, ja es esmu rakstījis šīs klases un diezgan regulāri izmantoju, es to neaizmirsīšu, bet, ja kāds jauns iesaistās projektā, tad šāda dokumentācija viņa darba ātrumu daudzkāršo.

 

P.S. Es šeit izteicos tieši par funkciju/metožu dokumentēšanu, jo tāda bija sākotnējā tēma.

Edited July 19, 2012 by codez

[daGrevis]

Dokumentācijai ir jābūt angliski.

[codez]

Dokumentācijai ir jābūt angliski.

Ne vienmēr.

Ja projekts tiek izstrādāts lokāli un tajā strādā tikai latvieši, tad latviešu valodā dokumentācija ir daudz ērtāka un ātrāk uztverama.

 

P.S. Varbūt forumā arī sākt sarakstīties angļu valodā? Kā ar lietotāju interfeisu aplikācijām, varbūt arī angliski?

Edited July 19, 2012 by codez

[daGrevis]

Ļoti reti ir tā, ka tu vari būt 100% drošs — neviens cits, izņemot latvietis, neskatīsies tavu kodu jebkad. Varbūt pēc pieciem gadiem projektā kļūdas labos norvēģu programmētāji.

 

P.S. Personīgi neuzskatu, ka tie visi latviešu termini (piemēram «palaistuve») padara dokumentāciju ērtāku un ātrāk uztveramu.

[codez]

daGrevis, nevis termini padara, bet gan ikdienā ierastā teikumu konstrukcija. Starp citu latviešu valoda ir krietni bagātāka šai ziņā un ļauj konstruēt teikumus, kas precīzāk un konstruktīvāk izsaka domu. Tos pašus terminus var lietot gan latviski, gan arī nelatviskotā formā.

 

Par to, ka varētu lietot kādi citi, tas arī reāli atkarīgs no situācijas. Ja projektu pārpērk, tad parasti projekta kodam ir 5% vērtība no visa projekta un pat ļoti bieži tas tiek pārrakstīts.

 

Piemēram, tie paši vācieši, gandrīz vienmēr komentē kodu vāciski. Nīderlandieši komentē flāmiski, utt. Vienkārši tās ir tautas kurām nav kompleksi pret savu valodu.

[Grey_Wolf]

Slikts kods.

Tāpēc saku - kods LAI IR dokumentācija.

Un vispār, ja runājam par f0ijām, nav jāraksta garas, nesaprotamas f-ijas. Īsas, smukas f-ijas, kas dara vienu konkrētu lietu. Pēc pašas f-ijas nosaukuma būtu jābūt skaidram, ko tā dara.

 

gribi teikt , ka šobrīd kodu raksti tāpat kā pirms gadiem 3-4 ???

un f-jas nevienmēr pasaka ko dara, piemēr ir no "Tomatu groza" - itkā pasaulē plaši izplatīta ..

nu izdomā ko dara šis f-jas ...

// class methods
function getCode() {
 	return $this->_code;
}

function getTitle() {
 	return $this->_title;
}

function getDescription() {
 	return $this->_description;
}

nush palika vieglak ???

[marrtins]

gribi teikt , ka šobrīd kodu raksti tāpat kā pirms gadiem 3-4 ???

Kāds sakars? :O Es pateicu, ko es gribēju pateikt.

 

Tavas visas f-ijas atgriež vērtību. Kas tur ko nesaprast? Faktiski, tās grūti saukt par f-ijām, drīzāk metodes, procedūras.

Lūk, f-ija:

function summa($a, $b){
   return $a + $b;
}

[marrtins]

Bob Martin - Clean Code( http://www.bookdepos...n/9780132350884 )

http://www.tvnet.lv/

[codez]

http://www.tvnet.lv/

 

Sinoptiķi brīdina par naktī gaidāmu stipru lietu 5

Šonakt Latvijā vietām gaidāms stiprs lietus, brīdina sinoptiķi.

[daGrevis]

Procedūra nemēdz atgriezt rezultātu.

[Grey_Wolf]

Kāds sakars? :O Es pateicu, ko es gribēju pateikt.

gribēju teikt, ka pēc gadiem 3 domāsi mazliet savādāk nekā šobrīd, un bez normāliem komentāriem pašm būs jāpavada zināms laiks, lai atcerētos savu tā brīža domu gājienu - programmešnas stilu

[marrtins]

Varbūt, bet tad arī savādāk rakstīsi komentārus :D

Procedūra nemēdz atgriezt rezultātu.

Tip tā VisualBasicā bija, ja?

[101111]

Tip tā VisualBasicā bija, ja?

 

Paskālā