# 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" ;)