cms/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ĄZUJĄCY dla programistów Watermelon CMS'a styl programowa-
  15    nia. Jeśli zauważysz, że ktoś zrobił inaczej, popraw. Jeśli robi to
  16    notorycznie - poinformuj go o tym.
  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          Po przecinku zawsze spacja!
  59
  60             funkcja(6, 8, 2);
  61
  62       d) Stringi
  63
  64          Normalnie używamy do stringów apostrofów. Cudzysłowy używamy dla
  65          zapytań SQL, oraz tam gdzie to konieczne (np. "\n")
  66
  67       e) Stałe itp.
  68
  69          Prawdę, fałsz i null zapisujemy tak:
  70
  71             TRUE
  72             FALSE
  73             NULL
  74
  75          Stałe piszemy także dużymi literami. Stałe samego CMS'a zaczynają
  76          się od WTRMLN_
  77
  78          Stałe własnych modułów MUSIMY poprzedzić prefiksem, aby mieć
  79          pewność, że nie będzie kolidowało z czymś innym. Przykład stałej
  80          własnego modułu:
  81
  82             INSZYNEWS_JAKIESDANE
  83
  84          Pamiętamy, żeby używać stałych we własnych modułach tylko jeśli
  85          to NAPRAWDĘ konieczne.
  86
  87    2. Styl programowania
  88
  89       a) Pobieranie danych z DB
  90
  91          Dane z bazy danych pobieramy do obiektu! Pobieranie danych poprzez
  92          funkcję result jest ZABRONIONE, a do tablicy odradzane.
  93
  94          Przykład pobrania danych, które jest OK:
  95
  96             $data = $this->db->query("SELECT * FROM `test`");
  97
  98             while($item = $data->to_obj())
  99             {
 100                echo $data->text;
 101             }
 102
 103       b) Działania na tablicach
 104
 105          Jeśli chcesz przejść po wszystkich elementach tablicy użyj foreach.
 106          for jest odradzane w tym przypadku.
 107
 108          DOBRZE:
 109
 110             foreach($array as $item)
 111             {
 112                echo $item;
 113             }
 114
 115          ŹLE:
 116
 117             for($i = 0 ; $i < count($array) ; $i++)
 118             {
 119                echo $array[$i];
 120             }
 121
 122          Myślę, że różnica czytelności obu przykładów pokazuje, dlaczego
 123          należy użyć foreach ;)
 124
 125       c) Globale
 126
 127          Pod ŻADNYM POZOREM NIE UŻYWAJ globali. Globale są do niczego.
 128
 129          Możliwe, że wydaje się Tobie, że potrzebujesz ich, ale są sposoby
 130          na obejście tego.
 131
 132          Jeśli potrzebujesz jakichś danych w kilku funkcjach w klasie, dodaj
 133          prywatną zmienną do klasy.
 134
 135          Jeśli potrzebujesz potrzebujesz jakichś danych przy kilku odpale-
 136          niach danej funkcji, użyj zmiennej statycznej.
 137
 138          Jeśli potrzebujesz danych jakiejś klasy w zupełnie różnych miejsca-
 139          ch kodu, użyj Singletona.
 140
 141             Przyjęliśmy, że tak to ma wyglądać:
 142
 143                /*
 144                 * object Instance()
 145                 *
 146                 * Singleton...
 147                 *
 148                 */
 149                 static function Instance()
 150                {
 151                   if(!self::$instance instanceof self)
 152                   self::$instance = new self;
 153                   return self::$instance;
 154                 }
 155
 156             oraz jeszcze zmienna:
 157
 158                private static $instance = NULL; // Singleton...
 159
 160    3. Pozostałe
 161
 162       Wszystkie pliki zapisujemy z kodowaniem UTF-8 i uniksowymi enterami,
 163       tzn. \n
 164
 165       Jeśli widzisz w projekcie jakiś stary i zaniedbany plik, możesz się
 166       upewnić co do poprawności tabów i enterów poprzez funkcję "Znajdź i
 167       zamień".
 168
 169       Taby:
 170
 171          Znajdź: "\t"
 172          Zamień: "   " <- tutaj trzy spacje
 173
 174       Entery
 175
 176          Znajdź: "\r"
 177          Zamień: "" <- nic
 178
 179       Projekt oryginalnie był pisany na windowsie na różnych edytorach
 180       jeszcze przed wprowadzeniem konkretnych zasad. Właśnie to spowodo-
 181       wało globalny "syf" w projekcie. W przypadku Eclipse PDT (w tym
 182       programie obecnie piszę wcms'a) możesz użyć File->Convert Line
 183       Delimeters To->Unix.
 184
 185