===============================================================================
       MOJE UWAGI I WSKAZWKI DLA LUDZI PRACUJCYCH NAD PROGRAMEM KADU
===============================================================================

Z powodu do sporego w ostatnim czasie zarwno biernego jak i
czynnego zainteresowania projektem Kadu wrd ludzi uywajcych
systemw unixowych, zapada decyzja (moja wasna, cho mam nadziej
na poparcie pozostaych czonkw projektu) i wszystkie zasady
dotyczce tworzenia i modyfikacji kodu zostan spisane i bd
aktualizowane na uytek developerw i osb trzecich przysyajcych
poprawki i rozszerzenia kodu.

Nie ukrywam, e wikszo zawartych tu pomysw i rozwiza pochodzi
z moich prywatnych dowiadcze. Jeli ktrych z developerw nie
zgadza si z czym to chtnie wezm udzia w dyskusji na ten temat.
amanie zasad tylko z przyczyn lenistwa i niechlujstwa bdzie oczywicie
zawzicie przeze mnie tpione ;)

ycz owocnego programowania
Adrian Smarzewski


===============================================================================
                 1. KADU JEST PROGRAMEM W JZYKU C++
===============================================================================

Pamitaj o tym! Jzyk C++ jest w duym stopniu spadkobierc jzyka C.
Praktycznie kady program napisany w jzyku C daje si skompilowa kompilatorem
C++. Nie zapominajcie jednak o tym "++". Wykorzystujcie si i klarowno
tego jzyka! Nie stosujcie archaicznych konstrukcji w C. Nie bjcie si
programowania obiektowego... klas, dziedziczenia, metod wirtualnych...

* Unikaj tworzenia samodzielnych funkcji. W zasadzie powinna by tylko jedna
  funkcja - "main". Reszta kodu niech bdzie zawarta wewntrz metod
  poszczeglnych klas.

* Pojcie, ktre moe mie wiele instancji np. "uytkownik", "ikona" itp.
  w bardzo naturalny sposb implementujemy za pomoc klasy. Zmienne (pola)
  wewntrz klasy nie powinny by publiczne. Jeli chcesz zaimplementowa
  waciwo X ktra moe by zmieniana z zewntrz stwrz prywatn zmienn
  X i dwie publiczne metody: setX() zmieniajc dan warto i zwracajc
  j x().

* Pojcie, ktre nie powininno mie wicej ni jednej instancji np.
  "autostatus" czy "menader emotikonw" rwnie powinno si implementowa
  za pomoc klasy.
    
  Jeli obiekt twojej klasy X ma by utworzony przy starcie aplikacji i
  nie jest zaleny od innych obiektw (czyli moe np. by utworzony jako
  pierwszy) moesz zaimplementowa kod jako zwyk klas oraz zadeklarowa
  jedn zmienn klasy X o nazwie np x bdc t jedyn instancj klasy
  (pojcia).
  
  xxx.h:
  ------
  
  class X
  {
  	public:
  		X();
		void m();
  };
  
  extern X x;
  
  xxx.cpp:
  --------
  
  X::X()
  {
  };
  
  void X::m()
  {
  };
  
  X x;
  
  Jeli chcesz, aby z pozostaej czsci kodu mona byo kontrolowa kiedy
  obiekt ten bdzie utworzony, a kiedy zniszczony powiniene zadeklarowa
  statyczne (static) publiczne metody create(), destroy() lub on(), off()
  lub te enable(), disable() w zalenoci 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. Uywaj np. klasy QFile zamiast
  funkcji fopen(), fwrite() itp.

* Uywaj mechanizmu sygnaw tam gdzie tylko jest to moliwe i nie powoduje
  zbytniego zamieszania. Sygnay i sloty to rozwizania eleganckie i warto
  z nich korzysta.

* Wzorujc si na standardach QT przyjmujemy, e:

	- nazwy metod rozpoczynaj si od maej litery, a drugi i kolejne
	  wyrazy nazwy rozpoczynamy wielk liter, np: activate(), getFocus()
	  
	- w nazwach klas kady wyraz nazwy cznie z pierwszym rozpoczynamy
	  wielk liter, np: PendingMsgs, EmoticonsManager
	  

===============================================================================
                    3. WYGLAD KODU - ZASADY SKADNI
===============================================================================

* Wszystkie wcicia 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 programw do automatycznego
  tworzenia dokumentacji przy uyciu kodu rdowego (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
		...
	};

* Wyraenie warunkowe

	if(<warunek>)
		instrukcja;

	if(<warunek>)
	{
		instrukcja 1;
		instrukcja 2;
		...
	};

* Ptla while (for i do/while podobnie)

	while(<warunek>)
		instrukcja;

	while(<warunek>)
	{
		instrukcja 1;
		instrukcja 2;
		...
	};


===============================================================================
                    4. ZASADY PRACY W GRUPIE NAD PROJEKTEM 
===============================================================================

* Jeli nie masz praw zapisu do CVS przysyaj developerom patche, tworzone
  poleceniem "diff -u". Najlepiej generowa je wzgldem najwieszej wersji
  z CVS, ale nie jest to wymagane, jeli w midzyczasie nie byo powanych
  zmian w kodzie. Patche, ktre nie nao si poprawnie na aktualny kod
  bd odrzucane.

* Jeli masz prawa zapisu do CVS sprawd poleceniem "cvs editors" czy pliki,
  ktre masz ochot zmodyfikowa nie s wanie przypadkiem przez kogo
  zmieniane. Nastpnie poleceniem "cvs edit" powiadom innych developerw
  o fakcie rozpoczcia modyfikacji. Podczas aktualizowania rde na CVS
  podawaj w miar krtkie, lecz sensowne opisy dokonywanych modyfikacji
  (cvs commit -m "opis").

* Jeli dokonywana zmiana nie jest tylko poprawk kodu, lecz dotyczy
  funkcjonalnoci programu, nie powiniene podejmowa decyzji samodzielnie.
  Skonsultuj planowan modyfikacj lub rozbudow z pozostaymi programistami
  nawet jeli sprawa jest wymieniona w pliku TODO. Przy mniejszych zmianach
  (nie wywracajcych projektu do gry nogami) wystarczy akceptacja ktrego
  ze "starych wyjadaczy" ;)
