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

Valid HTML 4.01!