Styl programowania przyjety na Programowaniu Mikrokontrolerow
*************************************************************
(na podstawie stylu programowania przyjętego na Wydziale MIM UW,
ale to generalnie dobry styl programowania)

0 Spis tresci:
--------------
	1 Ogolne reguly
	2 Nazewnictwo
	3 Pliki naglowkowe
	4 Zasady dobrego i czytelnego umieszczania poszczegolnych konstrukcji


1 Ogolne reguly
---------------
1.1	Ocenie podlegaja jedynie kompletne programy umieszczone
	w oddzielnym katalogu.
1.2	Kazdy program musi byc zaopatrzony w Makefile.
1.2.1	Wywolanie make bez parametrow musi przeprowadzic kompilacje
	wszystkich komponentow.
1.2.2	Wywolanie 'make update' musi do podlaczonego ukladu wgrywac program.
1.2.3	Wywolanie 'make clean' musi usuwac wszystkie wyniki kompilacji.
1.3	Programy sa kompilowane z opcja -Wall i nie moga generowac zadnych
	ostrzezen.
1.4	Kazdy program musi byc zaopatrzony w README z opisem co robi program.
1.5	Programy musza dzialac co najmniej w pracowni studenckiej.
	Tlumaczenie, ze program dziala w domu, nie bedzie brane pod uwage.
1.6	Poleceniem #include mozna dolaczac jedynie pliki naglowkowe (*.h).
1.7	Deklaracje wspolne dla kilku plikow zrodlowych umieszcza sie w plikach
	naglowkowych (wystepowanie duplikatow definicji, deklaracji i
	makrodefinicji w plikach zrodlowych swiadczy o niechlujstwie i zle
	postrzegane).
1.8	Uzywanie zmiennych globalnych jest zakazane. Wszystkie dane nalezy 
	przekazywac przez parametry podprogramow.
1.8.1	Wyjatkiem sa sytuacje, w ktorych bez zmiennych globalnych absolutnie
	nie da sie napisac programu.
1.9	Uzywanie instrukcji goto jest zakazane.
1.10	Wartosci przekazywane przez wywolania systemowe musza byc badane.
1.11	Identyfikatory i komentarze musza byc zapisywane spojnie, w takim samym
	jezyku (polskim lub angielskim).

2 Nazewnictwo
-------------
2.1	Deklaracja funkcji main(...) umieszczona jest w pliku main.c lub main.cc.
2.2	Identyfikatory powinny byc znaczace.
2.3	Nazwy makrodefinicji piszemy wielkimi literami.
2.4	Dodatkowo: patrz punkt 1.11

3 Pliki naglowkowe
------------------
3.1	Plik naglowkowy moze zawierac jedynie:
3.1.1	Makrodefinicje,
3.1.2	Deklaracje podprogramow,
3.1.3	Deklaracje struktur,
3.1.4	Deklaracje typow (typedef).
3.2	Plik naglowkowy nazwa.h ma format:

#ifndef _NAZWA_H_
#define _NAZWA_H_

			/* deklaracje i makrodefinicje */
#endif

4 Zasady dobrego i czytelnego umieszczania poszczegolnych konstrukcji
---------------------------------------------------------------------
4.1	Separatory
4.1.1	Przed przecinkiem nie wystepuje spacja. Po przecinku jest jedna spacja.
	np. mnoz(345, 657)
4.1.2	Operatory -> . nie moga miec spacji po zadnej stronie.
	np. osoba.nazwisko biezacy->nastepny
4.1.3	Po prawej stronie jednoargumentowego minusa nie moze wystapic spacja.
	np. y = -x;	y = 2 * (-x + 3); 
4.1.4	Po nawiasie otwierajacym i przed nawiasem zamykajacym nie 
	moze wystapic spacja. Dotyczy wszystkich rodzajow nawiasow.
4.1.5	Pozostale operatory sa otoczone pojedyncza spacja, 
	np. znaleziony = pozycja + 5;
4.2	W deklaracjach zmiennych wskaznikowych gwiazdke umieszcza sie przy nazwie 
	zmiennej, np. int *miejsce;
4.3	Deklaracja struktury (lub unii) ma postac: 

struct nazwa {
	typ1 pole1;
	typ2 pole2;
	...
}; 

4.4 Deklaracja funkcji ma postac:

typ_wyniku nazwa(typ_arg1 p_arg1, ..., typ_argn argn);

4.5 Definicja funkcji ma postac:

typ_wyniku nazwa(typ_arg1 p_arg1, ..., typ_argn argn)
{
	typ_zmiennej_lokalnej1 v_zmienna1;
	typ_zmiennej_lokalnej2 v_zmienna2;
	...

	instrukcje;
}

4.6 Instrukcja switch ma nastepujaca postac:

switch (wyrazenie) {
	case stala1:
		instrukcje;
	case stala2:
		instrukcje;
	...
	default:
	instrukcje;
}

4.7.1	Fraza default musi wystepowac nawet jesli wydaje sie to bez sensu
	(kontrola bledow).
4.7.2	Kazde fraza case ... powinna konczyc sie instrukcja break, exit,
	return, syserr lub fatal.
4.7.2.1	Brak break wymaga komentarza.

5 Format plikow zrodlowych (*.c lub *.cc)
--------------------------------
5.1	Na poczatku wystepuja polecenia #include.
5.1.1	Pierwsze ida pliki bibliotek standardowych (#include <...>).
5.1.2	Za nimi (po jednej pustej linii) pliki bibliotek uzytkownika
	(#include "...").
5.2	Za #include wystepuja deklaracje, ktore moglyby znalezc sie w pliku
	naglowkowym (punkt 3.1).
5.2.1	Jesli jakas deklaracja wystapilaby w wiecej niz jednym pliku 
	zrodlowym nalezy ja przeniesc do pliku naglowkowego.
5.3	Za deklaracjami wystepuja definicje funkcji.
5.3.1	Kolejne definicje fukcji sa poodzielane co najmniej jedna
	wolna linia.

6 Komentarze
------------
6.1	Stosujemy znane z C, czyli /* ... */ oraz // 
6.2	Komentarze wystepuja tylko tam gdzie znaczenie programu nie jest oczywiste
	i jasno nie wynika z konstrukcji i znaczacych identfikatorow.
6.2.1	Godna najwyzszej kary glupota jest pisanie komentarzy typu:
	i++; // zwiekszenie i o jeden
6.3	Komentarza wymagaja bardziej skomplikowane i nieintuicyjne konstrukcje,
   	oraz pola struktur, unii, zmienne i parametry, ktorych przeznaczenie nie
	wynika jasno z ich nazwy.
6.3.1	Dobry komentarz do instrukcji/zmiennej ma postac:
		
	instrukcja;	// komentarz krotki

	instrukcja;
	/* komentarz                                       *
	 * bardzo                                          *
	 * dluuuuuuuuuuuuuu uuuuuuuuuuuuuuuuuuuuuuuuuuuugi */	 
6.4	Ze wzgledow estetycznych warto zadbac aby ograniczniki komentarzy
	wystepowaly w tych samych kolumnach (tak jak wyzej).

6.5 Komentarz do funkcji ma postac:

typ_wyniku nazwa(typ_arg1 arg1, ..., typ_argn argn);
/* opis co funkcja robi         *
 * ...                          *
 * MODYFIKOWANE PARAMETRY: ...  */

6.5.1	MODYFIKOWANE PARAMETRY: ... opuszcza sie, gdy ta lista jest pusta.
6.5.1.1	Przez modyfikowane parametry rozumie sie parametry wskazujace
	obszary pamieci, ktorych zawartosc ulegnie zmianie.