PHP funkciju komentāri

[aaxc]

Jautājums: Kā nosaka īsti pareizais stils rakstīt vai nerakstīt komentārus pie funkcijām, kuru darbība ir pašsaprotama?

Piemēram:

 

# set '$krd_server' variable
private function setKrdServer( $krd_server ) {
$this -> krd_server = $krd_server;
}

# get '$krd_server' variable
private function getKrdServer () {
return $this -> krd_server;
}

# set '$krd_username' variable
private function setKrdUsername ( $krd_username ) {
$this -> krd_username = $krd_username;
}

# get '$krd_username' variable
private function getKrdUsername () {
return $this -> krd_username;
}

# set '$krd_password' variable
private function setKrdPassword ( $krd_password ) {
$this -> krd_password = $krd_password;
}

# get '$krd_password' variable
private function getKrdPassword () {
return $this -> krd_password;
}

Man personīgi patīk, ka ir kautvai bezjēdzīgi, bet tomēr komentāri, bet interesē ko tieši "good practise" par to saka.

Edited July 19, 2012 by aaxc

[edgarsj]

Jautājums: Kā nosaka īsti pareizais stils rakstīt vai nerakstīt komentārus pie funkcijām, kuru darbība ir pašsaprotama?

Man personīgi patīk, ka ir kautvai bezjēdzīgi, bet tomēr komentāri, bet interesē ko tieši "good practise" par to saka.

 

Man nepatīk. Tikai lieks spams. Un good practice tas varētu būt tikai tad, ja nepieciešama auto ģenerēta api dokumentācija, kas izmanto komentārus.

[daGrevis]

Izmanto PhpDoc, nevis HashThatIsntDoc stilu.

 

/**
* Do something.
*
* @param  integer $foo Foo.
* @param  integer $bar Bar.
* @return array        Bazies.
*/

[codez]

izmantoju PhpDoc, kaut vai tā iemesla dēļ, lai IDEē redzētu kādas ir return vērtības, kas jāpadot funkcijai un ja atgrieztā vērtība ir kāda klase, tad, lai rādītu tālāk priekšā klases metodes un propertijus.

[aaxc]

Jā, bet tad kods vēl raibāks paliks.

[rATRIJS]

Es komentaarus rakstu tik tur, kur tie tieshaam ir nepiecieshami. PHPDoc man ar liekas, ka visu padara raibu un taa kaa es un man komandaa neviens IDE neizmanto, tad taa nav probleema. Nepiecieshamaa dokumentaacija tiek rakstiita atsevishkji.

[blackhalt]

Komentārus vajag! Man vienalga vai # // /**/ , ka tik vienots stils visā datnē.

[codez]

phpDoc vienas funkcijas/metodes ietvaros neko raibāku nepadara, bet pie pareizas abstrakcijas, kāda nozīme, kas ir citā funkcijā/metodē 20 rindiņas augstāk vai zemāk, savarīgs ir konkrētās vietas kods.

[briedis]

Hmm, nesaprotu, kā tie cilvēki iztiek bez IDEēm un jebkāda type-hintinga... Rezultātā redzu tikai 2 variantus - vai nu superīga atmiņa, ka visu var atcerēties, vai arī regulāra skraidīšana pa failiem un meklēšana "kā tad tur bija"..

 

ini_set('flame.text_editor_VS_IDE', true);

[aaxc]

Nu jā, te jau gandrīz poll jātaisa augšā: puse saka nevajag, otra - vajag ;)

[rpr]

vajag. izmantoju phpDOc un es jau to uztveru tīri kā funkciju atdalītāju, attiecīgi ja na nodokumentēta metode, es to varu arī palaist garām. ja kādam tas stipri traucē, var IDE uzlikt komentāriem krāsu, kas tuvu baltai :)

[marrtins]

Komentāri ir vajadzīgi tiešām sarežģītām vietām, kas apstāsta kāpēc tā un šitā, kas tas par haku un kas tas par ielāpu. Pats kods lai ir dokumentācija.

[Grey_Wolf]

Pats kods lai ir dokumentācija.

nu nu ... pēc gada, pats urbsies cauri savam kodam labu brīdi līdz sapratīsi ko tajā brīdī biji domājis ..

komentāri nekad nav par daudz .. protams ja viņi ir sakarīgi , un principā vienalga kādā stilā pierakstīti, galvenais lai viņi būtu

[Kavacky]

Ja kods ir īss un saprotams, tad tie obvious stila komentāri "$var +=1; // increment $var by 1" ir 0 vērtībā, to saprast var arī pēc miljons gadiem.

 

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

[marrtins]

urbsies cauri savam kodam labu brīdi līdz sapratīsi ko tajā brīdī biji domājis ..

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.