4DEVS

   1      #### ##### #   # #        ##### ### ####    ##   #    # ###   ##
   2     #    #  #   #   # #        #    # # #    #  #  #  ##   #  #   #  #
   3     #       #   #   # #        #    # # #      #    # # #  #  #  #    #
   4      ####   #    ###  #        #####  #  ####  ###### #  # #  #  ######
   5          #  #     #   #        #      #      # #    # #   ##  #  #    #
   6     #    #  #     #   #        #      # #    # #    # #    #  #  #    #
   7      ####   #     #   ######   #     ### ####  #    # #    # ### #    #
   8
   9                 STYL PISANIA KODU WATERMELON CMS-A
  10                                                      PRAWIE GOTOWE ...
  11                       LEKTURA OBOWIĄZKOWA!
  12 ____________________________________________________________________________
  13
  14    To jest obowiązyjący dla programistów Watermelon CMS-a styl programowa-
  15    nia. Jednolity styl poprawia wygląd kodu i ułatwia jego późniejszą refa-
  16    ktoryzację. Jeśli zauważysz, że ktoś zrobił inaczej, popraw.
  17
  18    1. Wygląd kodu
  19
  20       a) Taby
  21
  22          Nie ma tabów. Zamiast tabów trzy spacje!
  23
  24       b) Klamerki
  25
  26          Typowy styl - przed i po klamerce enter.
  27
  28          if(blablabla)
  29          {
  30             test();
  31          }
  32          else
  33          {
  34             test();
  35          }
  36
  37       c) Operatory
  38
  39          Przed i po operatorze spacja.
  40
  41             $abcde = $x + ( 6 + 2 ) . 'abc';
  42
  43          Co do nawiasów - dotyczy tylko wyrażeń, czyli:
  44
  45             if(abc);
  46
  47          oraz
  48
  49             jakas_funkcja(); // nie robimy po nazwie funkcji spacji -
  50                              // według nas jest to psucie czytelności.
  51
  52          ale
  53
  54             $test = ( $a * $h ) / 2;
  55
  56          Pisanie spacji nie dotyczy operatorów zasięgu ( "::" oraz "->" )
  57
  58          Foo::Bar();
  59          $foo->bar();
  60
  61          Po przecinku zawsze spacja!
  62
  63             funkcja(6, 8, 2);
  64
  65       d) Stringi
  66
  67          Normalnie używamy do stringów apostrofów. Cudzysłowy używamy dla
  68          zapytań SQL, oraz tam gdzie to konieczne (np. "\n")
  69
  70       e) Stałe itp.
  71
  72          Stałe piszemy także dużymi literami. Stałe samego CMS-a zaczynają
  73          się od WTRMLN_
  74
  75          Stałe są używane tylko przez sam CMS. Moduły nie korzystają ze
  76          stałych, ponieważ jest to mało wygodne i mało elastyczne. Jeśli
  77          jednak z jakiegoś powodu MUSISZ (np. dla testów) użyć stałej, to
  78          dodaj do niej prefiks, żeby nie kolidowała z niczym innym.
  79
  80    2. Styl programowania
  81
  82       a) Pobieranie danych z DB
  83
  84          Dane z bazy danych pobieramy do obiektu. Nie pobieramy nic przez
  85          funkcję mysql_result. Ewentualnie można użyć tablicy zamiast
  86          obiektu, ale raczej preferujemy obiekty (kod wygląda czytelniej)
  87
  88          Przykład pobrania danych, które jest OK:
  89
  90             $data = $this->db->query("SELECT * FROM `test`");
  91
  92             while($item = $data->to_obj())
  93             {
  94                echo $data->text;
  95             }
  96
  97       b) Działania na tablicach
  98
  99          Jeśli chcesz przejść po wszystkich elementach tablicy użyj foreach,
 100          ponieważ jest dużo czytelniejsze od for. Ewentualnie można użyć
 101          funkcji typu array_map, ale jest to raczej mniej wygodne i mniej
 102          czytelne.
 103
 104          DOBRZE:
 105
 106             foreach($array as $item)
 107             {
 108                echo $item;
 109             }
 110
 111          ŹLE:
 112
 113             for($i = 0 ; $i < count($array) ; $i++)
 114             {
 115                echo $array[$i];
 116             }
 117
 118          Myślę, że różnica czytelności obu przykładów pokazuje, dlaczego
 119          prawie zawsze lepiej użyć foreach ;)
 120
 121       c) Globale
 122
 123          Nie używamy słowa kluczowego global. To jest stare rozwiązanie.
 124          Wydaje się proste w użyciu i wygodne, ale w rzeczywistości powoduje
 125          śmietnik w kodzie. Po za tym AFAIK od PHP6 nie będzie już globali.
 126          Zamiast globali można użyć właściwości klas, słowa kluczowego
 127          static, rejestru (wzorzec projektowy registry) itp. Można by było
 128          też użyć singletona, ale w Watermelonie NIE UŻYWAMY singletona.
 129
 130       d) Pętle for
 131
 132          W pętlach for liczbę iteracji piszemy przed pierwszym średnikiem, a
 133          po nim jedynie robimy porównanie dwóch zmiennych.
 134
 135          DOBRZE:
 136
 137             for($i = 0, $j = count($array) ; $i < $j ; $i++)
 138             {
 139                echo $array[$i];
 140             }
 141
 142          ŹLE:
 143
 144             for($i = 0 ; $i < count($array) ; $i++)
 145             {
 146                echo $array[$i];
 147             }
 148
 149          Ot, taki dobry nawyk. Po co po każdej iteracji ma wykonywać jakąś
 150          funkcję (w tym przypadku count()), skoro zwracana wartość jest
 151          stała...
 152
 153    3. Pozostałe
 154
 155       Wszystkie pliki zapisujemy z kodowaniem UTF-8 i uniksowymi enterami,
 156       tzn. \n, nie \r\n jak w Windowsie.
 157
 158