Toto je zavazny dokumnet, ktory musime vsetci dodrzovat pri pisani kodu.. Samozrejme je mozne sa dohodnut na tom, ako to bude, aby to vyhovovalo temer vsetkym, ale konsenzus sa nam pravdepodobne i tak nepodari.. Takze nejak to vymyslime a basta.

Contents 1 Indentation 2 Code blocks 3 Code vs. Output 4 Global data 5 Control flow 6 Control blocks 7 Switch indentation 8 Constants 9 NOP and Fallthrough 10 Long lines 11 Comments 12 More 13 Runtime and memory 14 PHP functions 15 Forbidden!!

Indentation

Na indentaciu vsetkeho zdrojaku pouzivajte TABy, nie medzery. Na dalsie odstadzovanie, napr. priradeni a komentarov medzery, nie TABy. Dbajte na to, aby sa zdrojovy kod nerozbil, ked si niekto zmeni sirku TABov.

------->int $count = 10;___/* $count is.. */
------->int $i____ = 1;____/* $i is.. */

-------> is a TAB; _ is a SPACE.

Code blocks

Vzdy pouzivajte kompletny php-otvaraci tag <?php. Ziadne skratky typu <? a pod.

<?php ... ?>

Code vs. Output

Rozdelujte zdrojoy kod na ten, ktory pocita a ten ktory vypisuje. Inymi slovami piste zvlast funkcie, ktore nieco nacitaju, odfiltruju, zosortia, rozdelia a vyhodnotia; a zvlast funkcie, ktore spocitane data uz iba zobrazia. Ostatne, aktualny control flow navrh vas k tomu tak trochu nuti..

Global data

Nepouzivajte ziadne globalne premenne a funkcie, vyjma tych, ktore su celoprojektovo dohodnute. Nepouzivajte priamo premenne z $_REQUEST. Vzdy volajte funkcie, ktore tieto parametre spostredkovavaju. Dovod je jednoduchy, nikdy neviete, kto vas preco zavola. I veci na prvy pohlad globalne ci staticke nemusia byt uplne globalne a staticke. Poznamka: Niekde v inicializacii kodu sa kompletne odmaze vsetko z globalneho priestoru a na konci kodu sa testuje, kolko globanych veci pribudlo.. nemali by tam byt ziadne..

Control flow

Za if, while, for, switch, ... vkladajte medzeru. nasledujuce prikazy piste vzdy na novy riadok.

if ($test)
   return false;

while ($count++ < $total)
   echo $count;

if (!$test)
   throw new Exception ('$test failed');

Control blocks

Viacprikazove bloky if, while, for, switch, ... piste vzdy ceckovou notaciou.

if ($test)
{
   ...;
   ...;
}

Vnorene viacprikazove bloky prikazy kompletne oznacte:

if ($test1)
{
   if ($test2)
   {
      ...;
      ...;
   }
}
else
{
   ...;
}

Jednu vynimku by sme si tu mohli dovolit, ale iba na miestach, kde nebude mat vazny dopad na prehladnost.. (za else vsak nesmie ist nic ine nez jednoduchy return alebo throw ).

if ($test1)
{
   ...;
}
else return false;

Switch indentation

Odsadzujte jednotlive case o jeden TAB od urovne switch-u. Kazdy case na novy riadok. Break ako posledny prikaz bloku case tiez na novy riadok..

switch ($a)
{
   case A:
      ...;
      break;
   case B:
   case C:
      ...;
      break;
}

Pokial by sa snad stalo, ze switch by bol obrovsky a jeho riadky jednoduche a navzajom velmi podobne, je obcas vhodnejsie pouzit tabulkovy zapis:

switch ($a)
{
   case 1:   call_function ("add");      break;
   case 2:   call_function ("edit");     break;
   case 3:   call_function ("delete");   break;
   default:  call_function ("cancel");   break;
}

Constants

Vzdy si definujte konstanty, ked nieco pocitate. Konstanty sa pisu velkymi pismenami.

• local constant, defined in AlbumPage class

   const MAX_PAGE_ITEMS = 30;

   for ($i = 0; $i < self::MAX_PAGE_ITEMS; $i++)
      ...;

• global constant, defined in defines.php

define ("MAX_LIST_LENGTH", 30);

for ($i = 0; $i < MAX_LIST_LENGTH; $i++)
   ...;

NOP and Fallthrough

Oznacte komentarmy prazdne prikazy.

while ($a[i++] = $b[j++])
   /*nop*/;

Oznacte komentarmy pre-padavajuce case bloky

switch ($a)
{
   case A:
      ...;
      break;
   case B:
   case C:
      ...;
      /*fall*/
   case D:
      ...;
      break;
}

Long lines

Zalamujte dlhe riadky. Odsadzujte zalomenie TABmy. Operator (napr +) davajte az na novy riadok.

$result = $loooooooooooongVariable1 + $loooooooooooongVariable2
   + $loooooooooooongVariable3 + $loooooooooooongVariable4
   + $loooooooooooongVariable5 + $loooooooooooongVariable6;

Pripadne tiez krajsia verzia:

$result =
   $loooooooooooongVariable1 + $loooooooooooongVariable2
   + $loooooooooooongVariable3 + $loooooooooooongVariable4
   + $loooooooooooongVariable5 + $loooooooooooongVariable6;

Vzdy indentujte dlhe podmienky a vzdy zacnite novym riadkom. V poobnych pripadoch vzdy pouzivajte kompletnu blokovu { ... } notaciu, aj keby v nej mal byt iba jeden prikaz.

if (
   $loooooooooooongVariable1 == $loooooooooooongVariable2
   && $loooooooooooongVariable3 == $loooooooooooongVariable4
)
{
   ...;
}

Comments

Dokumentujte poriadne kazdu public a protected funkciu v style phpDoc (podobne ako JavaDoc).

Dokumentujte riadky kodu, aby bolo jasne, co maju zhruba robit bez kompilovania samotneho kodu. Prehladny sposob je napisat riadok s komentarom, ktory zhrnie, co sa bude robit a potom napisat blok prikazov, ktore to spravia. Za takymto blokom pride vzdy volny riadok.

/**
 * This function generates an html code for an external link.
 *
 * @param  string $url     URL to be used as a link.
 * @param  string $str     String to be displayed in the link. If not specified or blank, $url is used as $str.
 * @param  string $target  Target window of the the link.
 * @param  string $class   Class of the link html entity.
 *
 * @return string HTML code of the created link.
 */
 function MakeLink ($url, $str = "", $target = "", $class = "")
 {
   // start the link code..
   $result = '<a href="'.htmlspecialchars ($url).'"';

   // add link target, if specified
   if ($target)
     $result.= ' target="'.$target.'"';

   // add link class, if specified
   if ($class)
     $result.= ' class="'.$class.'"';

   // use $url as $str, if no $str specified
   if (!$str)
     $str = $url;

   // add the $str and finish the link code
   $result.= '>'.htmlspecialchars ($str).'</a>';

   // return the link code
   return $result;
 }

More

Takto nejak by mal vypadat kazdy zdrojovy subor.

• na zaciatku je potrebne zdokumentovat samotny subor, inak phpDoc nefunguje spravne.. (minimalne @package a @subpackage)
• kazdy include by mal obsahovat verifikaciu, ze defined ("FOTO") === true.
• kazdu triedu je potrebne zdokumentovat zvlast, inak phpDoc nefunguje spravne.. (minimalne @package a @subpackage)

<?php
/**
 * Defines HtmlLink class.
 * @package Foto
 * @subpackage Html
 * @author Juraj Simlovic
 */
if (defined ("FOTO") === false) exit;

/**
 * This class is supposed to do this and that..
 *
 * Note: Use this and that function to do this and that, instead of another
 * methods, because it is not very wise to do it another way.
 *
 * @package Foto
 * @subpackage Html
 */
class HtmlLink extends Link
{
  /**
   * @var string All public properties come first. Although they are not
   * welcome, they might be useful sometimes. This is text to be used for the
   * link.
   */
  public $str = "";

  /**
   * Constructor as the first public function. It creates an HtmlLink from
   * the given Request.
   *
   * @param Request &$request Request to be used to create params of the
   * HtmlLink. If no Request is given, an empty Request is used, resulting in
   * no params.
   */
  public function __contruct (Request &$request = new Request ())
  { ... }
   
  /** 
   * All public functions come next and this is the first of them.
   *
   * @return string Returns valid HTML code for the link.
   */
  public function GetCode ()
  { ... }

  // All private properties come after all public methods. They does
  // not need to be documented as precisely as public ones. However,
  // add at least a simple comment of its main purpose.
  private $params = array (); // This stores all params of the link..

  /**
   * All private functions come last and this is the first of them.
   * It is not wise to mix private functions with public ones, but we shall
   * not forbid it strictly.
   */
  private function GetUrl ()
  { ... }

}

?>

Runtime and memory

• memory_get_usage()

Pouzivajte funkcie, ktore vam naznacia, ako hospodarite s pamatou a s vypoctovym casom. Nechceme predsa dopadnut ako mediawiki.. :))

PHP functions

Nepouzivajte zbytocne huste konstrukty, ked existuje jednoduchy zabudovany ekvivalent:

Forbidden!!

Neblokovy if-else blok obsahujuci blokovy if blok.

if ($test1)
   if ($test2)
   {
      ...;
      ...;
   }
else
   ...;

Vypis obsahu premennej pomocou <?=.

Some sentence with a dynamic <?= $value; ?> inside.

Setrenie prikazu echo.

Some sentence with a <?php if ($test) { ?>value1<?php } else { ?>value2<?php } ?>.

Neuplny if blok zo zalomenou podmienkou.

if (
   $loooooooooooongVariable1 == $loooooooooooongVariable2
   && $loooooooooooongVariable3 == $loooooooooooongVariable4
)
   ....;

Zle zalomena podmienka.

if ($loooooooooooongVariable1 == $loooooooooooongVariable2
   && $loooooooooooongVariable3 == $loooooooooooongVariable4)
{
   ....;
}

Cyklus bez definovanej konstanty.

for ($i = 0; $i < 30; $i++)
   ...;

Uplny gulas vstupnych podmienok:

if (!$script) throw new Exception ('$script value is invalid');
if (!isset ($this->path) || !is_array ($this->path)) throw new Exception ('$path not set');
if (empty ($this->params)) throw new Exception ('$params not set');