logi sisse meist KKK

Kust leida hea näidis või juhis selle kohta kuidas tuleks dokumenteerida PHP koodi? Selline, kus dokumenteerimine oleks minimaalne, kuid samas piisav selleks, et keegi teine kodeerija 2 aastat hiljem sellest abi saaks?

küsitud Oct 19 '09 at 20:43

Urmo%20Kaber's gravatar image

Urmo Kaber ♦♦
2234812

edited Oct 19 '09 at 20:51


Minu arust ilmekad muutujate ja funktsioonide nimed on juba iseenesest piisav dokumentatsioon. Kui kommenteerida, siis peaks kommentaar vastama küsimusele "miks?", mitte küsimusele "mida tehakse?". Seda viimast saab iga programmeerija koodist isegi aru.

Näiteks:

// Kui nimes on täpitähti, siis on nimi kodeeritud UCS-2 kooditabelis, muidu lihtne ASCII.
function idcard_decode($s)
{
  // kirvemeetod UCS-2 detectimiseks
  if (ord($s[0]) == 0 || ord($s[0]) == 1)
  {
    return mb_convert_encoding($s, 'UTF-8', 'UCS-2');
  }
  else
  {
    return $s;
  }
}

Mitte:

// Dekodeerib ID-kaardi nime
function idcard_decode($s)
{
  // kontrollib kas esimene bait on 0 või 1 
  if (ord($s[0]) == 0 || ord($s[0]) == 1)
  {
    return mb_convert_encoding($s, 'UTF-8', 'UCS-2');
  }
  else
  {
    return $s;
  }
}

Kodeerimise stiili mõttes tundub PHP-s standardiks saamas Zend Framework Coding Standard.

link

vastatud Oct 21 '09 at 12:35

Tambet%20Matiisen's gravatar image

Tambet Matiisen ♦♦
77791125

edited Oct 21 '09 at 12:40

Kui sa otsid võimalikult minimaalset varianti siis kodeerimisstandardid selle koha pealt väga palju ei aita. Näiteks toosama Zend Framework Coding Standard nõuab, et sa kirjutaks iga faili algusesse suure lataka kommentaari koos hulga @-annotatsioonidega. Mu meelest on nimetatud standard vähemasti kommenteerimise koha pealt täielik overkill.

Ka igasuguste automaatse dokumentatsiooni generaatorite a'la phpDocumentor kasutamine kipub nõudma suurema hulga kommentaaride kirjutamist kui tegelikult tarvilik oleks. Näiteks kui funktsiooni nimest ja parameetritest on ilmselge mida too funktsioon teeb.

Nagu Tambet ütles, tuleks dokumenteerida miks kood üht või teist asja teeb. Kuid üksnes sellest ei piisa - väga sageli on tarvis dokumenteerida ka mida see kood ikkagi teeb. Mõned näited:

class Date {
  // On ilmne, et see funktsioon tagastab aastaarvu
  public function getYear() {
  }
  // Siingi on üpris kenasti aru saada, et tagastatakse
  // nädalapäeva number, kuid see pole piisav, sest nädal
  // võib ju alata nii esmaspäeva kui pühapäevaga ning
  // loendamist võib alustada nii nullist kui ühest.
  public function getWeekDayNumber() {
  }
  // Taas ütleb funktsiooni nimi kenasti ära et tagastatakse
  // kalendrikuu nimi. Aga millises keeles?
  public function getMonthName() {
  }
}

Funktsioonide sisu enamasti kommenteerimist ei vaja, kui just ei tehta midagi eriliselt peent ja keerukat. Aga enamasti on parem see keerukas asi eraldi funktsiooni tõsta ja siis juba toda funktsiooni kommenteerida.

link

vastatud Oct 24 '09 at 11:48

Rene%20Saarsoo's gravatar image

Rene Saarsoo ♦♦
1.1k101121

Kui dokumenteerida koodi phpDocumentoriga, siis selle jaoks on olemas quickstart: http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.quickstart.pkg.html

link

vastatud Oct 21 '09 at 12:36

Tambet%20Matiisen's gravatar image

Tambet Matiisen ♦♦
77791125

Sinu vastus
lülita eelvaade

Jälgi seda küsimust

By Email:

Pärast sisselogimist saad tellida muudatuse teavitusi siit

By RSS:

Answers

Answers and Comments

Markdown Basics

  • *kaldkiri* või __kaldkiri__
  • **paks kiri** või __paks kiri__
  • link:[tekst](http://url.com/ "pealkiri")
  • pilt?![alt tekst](/path/img.jpg "pealkiri")
  • nummerdatud nimekiri: 1. Foo 2. Bar
  • to add a line break simply add two spaces to where you would like the new line to be.
  • põhilised HTML märgendid on samuti toetatud

Pinu tööpakkumised

kõik pakkumised »

Küsimuse sildid:

×22
×4

küsitud: Oct 19 '09 at 20:43

nähtud: 3,966 korda

viimati uuendatud: Oct 24 '09 at 11:48

Litsents: Creative Commons Attribution License | Kontakt: info@pinu.ee