Jump to content
php.lv forumi

PHP funkciju komentāri


aaxc

Recommended Posts

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

  • Replies 57
  • Created
  • Last Reply

Top Posters In This Topic

Top Posters In This Topic

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.

Link to comment
Share on other sites

Izmanto PhpDoc, nevis HashThatIsntDoc stilu.

 

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

Link to comment
Share on other sites

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.

Link to comment
Share on other sites

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.

Link to comment
Share on other sites

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

Link to comment
Share on other sites

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 :)

Link to comment
Share on other sites

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

Link to comment
Share on other sites

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

Link to comment
Share on other sites

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.

Link to comment
Share on other sites

Guest
This topic is now closed to further replies.

×
×
  • Create New...