# Instrukcja obsługi

### UWAGI I WSKAZÓWKI DLA LUDZI PRACUJĄCYCH NAD PROGRAMEM

Z powodu dość sporego w ostatnim czasie zarówno biernego jak i czynnego zainteresowania projektem Kadu wśród ludzi używających systemów unixowych, zapadła decyzja (moja własna, choć mam nadzieję na poparcie pozostałych członków projektu) iż wszystkie zasady dotyczące tworzenia i modyfikacji kodu zostaną spisane i będą aktualizowane na użytek developerów i osób trzecich przysyłających poprawki i rozszerzenia kodu.
Nie ukrywam, że większość zawartych tu pomysłów i rozwiązań pochodzi z moich prywatnych doświadczeń. Jeśli których z developerów nie zgadza się z czymś to chętnie wezmę udział w dyskusji na ten temat. Łamanie zasad tylko z przyczyn lenistwa i niechlujstwa będzie oczywiście zawzięcie przeze mnie tępione ;)
Życzę owocnego programowania
Adrian Smarzewski

### 1. KADU JEST PROGRAMEM W JĘZYKU C++

- Pamiętaj o tym! Język C++ jest w dużym stopniu spadkobiercą języka C. Praktycznie każdy program napisany w języku C daje się skompilować kompilatorem C++. Nie zapominajcie jednak o tym "++". Wykorzystujcie siłę i klarowność tego języka! Nie stosujcie archaicznych konstrukcji w C. Nie bójcie się programowania obiektowego ... klas, dziedziczenia, metod wirtualnych...
- Unikaj tworzenia samodzielnych funkcji. W zasadzie powinna być tylko jedna funkcja - "main". Reszta kodu niech będzie zawarta wewnątrz metod poszczególnych klas.
- Pojęcie, które może mieć wiele instancji np. "użytkownik", "ikona" itp. w bardzo naturalny sposób implementujemy za pomocą klasy. Zmienne (pola) wewnątrz klasy nie powinny być publiczne. Jeśli chcesz zaimplementować właściwość X która może być zmieniana z zewnątrz stwórz prywatną zmienną X i dwie publiczne metody: setX() zmieniającą daną wartość i zwracającą ją x().
- Pojęcie, które nie powinno mieć więcej niż jednej instancji np. "autostatus" czy "menadżer emotikonów" również powinno się implementować za pomocą klasy.
- Jeśli obiekt twojej klasy X ma być utworzony przy starcie aplikacji i nie jest zależny od innych obiektów (czyli może np. być utworzony jako pierwszy) możesz zaimplementować kod jako zwykłą klasę oraz zadeklarować jedną zmienną klasy X o nazwie np. x będącą tą jedyną instancją klasy (pojęcia).

      xxx.h:
      ------

      class X
      {
            public:
                    X();
                    void m();
      };

      extern X x;

      xxx.cpp:
      --------

      X::X()
      {
      };

      void X::m()
      {
      };

      X x;

- Jeśli chcesz, aby z pozostałej części kodu można było kontrolować kiedy obiekt ten będzie utworzony, a kiedy zniszczony powinieneś zadeklarować statyczne (static) publiczne metody create(), destroy() lub on(), off() lub też enable(), disable() w zależności od przeznaczenia tworzonej przez Ciebie klasy. Konstruktor takiej klasy powinien być prywatny. Zabroni to innym developerom utworzenia przez przypadek kolejnej instacji. Wszystkie metody powinny być statyczne i operować na obiekcie Instance.

      xxx.h:
      ------

      class X
      {
            private:
                    static X* Instance;
                    X();
            public:
                    static void create();
                    static void destroy();
                    static void m();
      };

      xxx.cpp:
      --------

      X::X()
      {
      };

      void X::create()
      {
            if(Instance==NULL)
                    Instance=new X();
      };

      void X::delete()
      {
            if(Instance!=NULL)
                    delete Instance;
      };

      void X::m()
      {
      };

      X* X::Instance=NULL;

### 2. KADU JEST PROGRAMEM OPARTYM O QT

- Staraj się wykorzystywać mechanizmy dostarczone przez bibliotekę QT zamiast funkcji z glibc lub kdelibs. Używaj np. klasy QFile zamiast funkcji fopen(), fwrite() itp.
- Używaj mechanizmu sygnałów tam gdzie tylko jest to możliwe i nie powoduje zbytniego zamieszania. Sygnały i sloty to rozwiązania eleganckie i warto z nich korzystać.
- Wzorując się na standardach QT przyjmujemy, że:
  - nazwy metod rozpoczynają się od małej litery, a drugi i kolejne wyrazy nazwy rozpoczynamy wielką literą, np.: activate(), getFocus()
  - w nazwach klas każdy wyraz nazwy łącznie z pierwszym rozpoczynamy wielką literą, np.: PendingMsgs, EmoticonsManager

### 3. WYGLAD KODU - ZASADY SKŁADNI

- Wszystkie wcięcia powinny być wykonywane za pomocą tabulacji a nie spacji! Sprawdź ustawienia swojego edytora.
- Komentarze przed deklaracjami klas i funkcji powinny być otoczone symbolami "/**" i "**/". Kod taki jest zgodny z wymogami programów do automatycznego tworzenia dokumentacji przy użyciu kodu źródłowego (np. kdoc).

Deklaracja klasy:

           /**
                    opis klasy
                    ...
            **/
             class «nazwa_klasy» : «lista_klas_podstawowych»
            {
                    private:
                            zmienna prywatna 1
                            zmienna prywatna 2
                            ...
                            metoda prywatna 1
                            metoda prywatna 2
                            ...
                    protected:
                            zmienna chroniona 1
                            zmienna chroniona 2
                            ...
                            /**
                                    opis metody chronionej 1
                            **/
                            metoda chroniona 1
                            /**
                                    opis metody chronionej 2
                            **/
                            metoda chroniona 2
                            ...
                    public:
                            /**
                                    opis publicznego konstruktora 1
                            **/
                            publiczny konstruktor 1
                            /**
                                    opis publicznego konstruktora 2
                            **/
                            publiczny konstruktor 2
                            ...
                            destruktor
                            /**
                                    opis metody publicznej 1
                            **/
                            metoda publiczna 1
                            /**
                                    opis metody publicznej 2
                            **/
                            metoda publiczna 2
                            ...
            };

Definiowanie metod:

            «nazwa_klasy»::«nazwa_metody»(«argument1»,«argument2»,...)
            {
                    treść funkcji
                    ...
            };

Wyrażenie warunkowe

            if(«warunek»)
                    instrukcja;

            if(«warunek»)
            {
                    instrukcja 1;
                    instrukcja 2;
                    ...
            };

Pętla while (for i do/while podobnie)

            while(«warunek»)
                    instrukcja;

            while(«warunek»)
            {
                    instrukcja 1;
                    instrukcja 2;
                    ...
            };

### 4. ZASADY PRACY W GRUPIE NAD PROJEKTEM

- Jeśli nie masz praw zapisu do CVS przysyłaj developerom patche, tworzone poleceniem "diff -u". Najlepiej generować je względem najświeższej wersji z CVS, ale nie jest to wymagane, jeśli w międzyczasie nie było poważnych zmian w kodzie. Patche, które nie nałożą się poprawnie na aktualny kod będą odrzucane.
- Jeśli masz prawa zapisu do CVS sprawdź poleceniem "cvs editors" czy pliki, które masz ochotę zmodyfikować nie są właśnie przypadkiem przez kogoś zmieniane. Następnie poleceniem "cvs edit" powiadom innych developerów o fakcie rozpoczęcia modyfikacji. Podczas aktualizowania źródeł na CVS podawaj w miarę krótkie, lecz sensowne opisy dokonywanych modyfikacji (cvs commit -m "opis").
- Jeśli dokonywana zmiana nie jest tylko poprawką kodu, lecz dotyczy funkcjonalności programu, nie powinieneś podejmować decyzji samodzielnie. Skonsultuj planowaną modyfikację lub rozbudowę z pozostałymi programistami nawet jeśli sprawa jest wymieniona w pliku TODO. Przy mniejszych zmianach (nie wywracających projektu do góry nogami) wystarczy akceptacja któregoś ze "starych wyjadaczy" ;)