Jump to content
php.lv forumi

PHP funkciju komentāri


aaxc

Recommended Posts

> 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

Link to comment
Share on other sites

  • Replies 57
  • Created
  • Last Reply

Top Posters In This Topic

Top Posters In This Topic

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 by codez
Link to comment
Share on other sites

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 by codez
Link to comment
Share on other sites

Ļ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.

Link to comment
Share on other sites

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.

Link to comment
Share on other sites

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 ???

Link to comment
Share on other sites

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;
}

Link to comment
Share on other sites

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

Link to comment
Share on other sites

Guest
This topic is now closed to further replies.

×
×
  • Create New...