Wygląd projektu.pdf

Standardy kodowania i dostarczania

projektów programistycznych

wersja 0.01

(szkic)

(październik 2010)

autor: Jan Kazimirski

Any fool can write code that a

computer can understand. Good

programmers write code that

humans can understand.

Martin Fowler

1 Wstęp

W związku ze słabą jakością oraz małą czytelnością przysyłanych do mnie projektów

programistycznych, postanowiłem przygotować dla Państwa zbiór reguł określających

sposób przygotowania projektów oraz zestaw standardów kodowania, które należy

wykorzystywać.

Od tej chwili wszystkie projekty programistyczne przysyłane do mnie w ramach

prowadzonych przeze mnie zajęć mają być przygotowane według przedstawionych

poniżej zasad. Zasady te przygotowane zostały pod kątem języka C++, ale większość

reguł znajdzie zastosowanie również do innych języków programowania, zarówno

obiektowych (np. PHP), jak i nieobiektowych (np. C).

Jednocześnie zastrzegam, iż w przypadku projektów, które nie będą stosowały się do

poniższych zasad, ocena końcowa projektu zostanie obniżona. W przypadkach

szczególnie drastycznych odstępstw od poniższych reguł, nie będę sprawdzał projektu i

student otrzyma ocenę taką samą jak gdyby w ogóle projektu nie dostarczył.

2 Zasady ogólne

2.1 Środowisko programistyczne

2.1.1 Wszystkie projekty są sprawdzane w środowisku Linux. Należy je więc tak

przygotować, aby mogły być kompilowane i wykonywane w tym środowisku. Jeżeli

instrukcja zadania nie stanowi inaczej należy stosować aktualne wersje narzędzi

dostępnych w ostatniej wydanej wersji dystrybucji Suse Linux.

2.1.2 Należy unikać stosowania niestandardowych bibliotek – w przypadku konieczności

ich użycia należy to wcześniej zgłosić oraz wyraźnie udokumentować w kodzie.

2.2 Sposób dostarczania projektu

2.2.1. Projekty należy dostarczać mailem na adres podany w instrukcji projektu. Projekty

jedno-plikowe należy przesyłać jako załączniki (nie należy wklejać kodu programu

w treść wiadomości). Projekty wielo-plikowe należy przed wysłaniem spakować.

Dopuszczalne metody kompresji to: tar+gzip, zip, arj, rar. Proszę nie zabezpieczać

archiwum hasłem. Przed wysłaniem należy sprawdzić spójność archiwum.

2.2.2. Nie należy wysyłać skompilowanych wersji projektu. Wysyłany projekt powinien

zawierać wszystkie elementy wymagane do kompilacji i wykonania (wyjątki – patrz

2.1.2 ).

2.2.3. Należy unikać lub ograniczać stosowanie w projektach elementów multimedialnych

(obrazków, zdjęć, animacji) – chyba że instrukcja wykonania projektu stanowi

inaczej.

2.2.4. Projekty należy dostarczać w terminach podanych w instrukcji projektu. W

przypadku projektów przysyłanych po terminie zastrzegam sobie prawo obniżenia

oceny lub odmowy oceny projektu.

2.3 Automatyczna kompilacja

2.3.1. Projekt wymagający kompilacji powinien zawierać odpowiednio przygotowany plik

Makefile lub skrypt powłoki pozwalający na automatyczną kompilację. Preferowane

jest stosowanie pliku Makefile.

2.3.2. W przypadku korzystania z programu make kompilacja całego projektu powinna być

domyślną regułą (polecenie 'make'). Dodatkowa reguła clean ('make clean') powinna

przywracać katalog projektu do postaci przed rozpoczęciem kompilacji. Opcjonalne

reguły: doc ('make doc')– tworzenie dokumentacji, tests ('make tests') – kompilacja

testów jednostkowych, runtests ('make runtests') – wykonanie testów

jednostkowych, demo ('make rundemo') – demonstracyjne wykonanie programu

(np. z przykładowymi danymi wejściowymi).

2.3.3. Jeżeli projekt nie korzysta z programu make, należy przygotować następujące

skrypty powłoki: makeme (kompilacja projektu z odpowiednimi opcjami

kompilatora i bibliotekami), cleanme (czyszczenie katalogu projektu – po wykonaniu

skryptu katalog projektu nie powinien zawierać żadnych plików binarnych i

tymczasowych, tylko oryginalne źródła przysłane przez studenta). Opcjonalne

skrypty: makedoc (generowanie dokumentacji), maketests (kompilacja testów

jednostkowych), runtests (wykonanie testów jednostkowych), rundemo

(demonstracyjne wykonanie programu – np. z przykładowymi danymi

wejściowymi).

3 Organizacja projektu, pliki

3.1 Rozszerzenia nazw plików

3.1.1. Pliki z kodem PHP powinny mieć rozszerzenia .php. Pliki z kodem C –

rozszerzenia .c. Dla kodu C++ należy używać rozszerzenia .C. Pliki nagłówkowe

zarówno dla kodu w C, jak i C++ powinny mieć rozszerzenia .h. Dla innych języków

programowania należy stosować rozszerzenia wymagane przez narzędzia (kompilatory

lub interpretery).

3.1.2. Pliki z dokumentacją w formacie ASCII powinny mieć rozszerzenie .txt, w

uzasadnionych przypadkach (np. konieczność użycia tabel, diagramów itp.) można

przygotować dokumentację w formacie Ms Word, OpenOffice Writer lub (preferowane)

pdf.

3.1.3. Jeżeli kompilacja lub wykonanie projektu wymaga dodatkowych działań (np.

instalacji bazy, konfiguracji firewalla itp.) to instrukcje tych działań należy umieścić w

pliku o nazwie README bez rozszerzenia.

3.2 Zawartość pliku

3.2.1. Pojedynczy plik z kodem nie powinien przekraczać 1000 linii. Dłuższe

projekty należy podzielić na kilka plików.

3.2.2. Wszystkie pliki z kodem powinny być czystymi plikami ASCII. Proszę nie

wysyłać kodu zapisanego w formatach edytorów (np. Word, OpenOffice itp.).

3.2.3. W przypadku niewielkich projektów każdy plik powinien zawierać jedną

funkcję lub klasę.

3.2.4. W dużych projektach (kilkadziesiąt funkcji lub klas) w jednym pliku należy

umieszczać funkcje i klasy, które są ze sobą powiązane funkcjonalnością (jeden plik –

jeden moduł).

4 Formatowanie i elementy stylu

4.1 Linie kodu

4.1.1. Długość linii kodu nie powinna przekraczać 78 znaków. Linie dłuższe należy

rozbić na kilka instrukcji lub złamać stosując składnię odpowiadającą danemu językowi

programowania.

4.1.2. W jednej linii należy umieszczać tylko jedną instrukcję.

4.1.3. W jednej linii należy umieszczać tylko jedną deklarację zmiennej.

4.2 Wcięcia i odstępy pionowe

4.2.1. Obowiązkowo należy stosować wcięcia do zaznaczenia bloków instrukcji

(ciało funkcji, instrukcji warunkowej, pętli itp.).

4.2.2. Do wcięć należy stosować spacje. Nie należy stosować znaków tabulacji

(chyba że jest to wymagane przez składni języka).

4.2.3. Wcięcia powinny mieć wielkość 4 spacji.

4.2.4. W celu oddzielenia poszczególnych bloków kodu (funkcje, klasy, fragmenty

kodu wykonujące jakieś specyficzne działania) należy stosować odstępy pionowe –

puste linie.

4.3 Stałe i zmienne

4.3.1. W projekcie nie należy stosować zmiennych globalnych. Wyjątkiem mogą być

języki, które nie dają innych możliwości przekazywania danych między blokami

programu.

4.3.2. Wszystkie „magiczne liczby” w projekcie powinny być zdefiniowane jako

stałe.

4.4 Instrukcje sterujące i nawiasy {}

4.4.1. W warunkowych, funkcjach i pętlach, otwierający nawias { należy umieszczać w

miarę możliwości w tej samej linii co instrukcja.

4.4.2. Nawias zamykający należy umieszczać w nowej linii.

4.4.3. W instrukcjach warunkowych i pętlach należy zawsze stosować instrukcje

grupujące, nawet jeżeli blok kodu składa się tylko z jednej instrukcji.

4.5 Funkcje

4.5.1. Funkcje powinny wykonywać jedną czynność.

4.5.2. Liczba parametrów funkcji nie powinna przekraczać 4. W uzasadnionych

przypadkach można odstąpić od tej reguły.

4.5.3. Długość funkcji nie powinna przekraczać 20-30 linii kodu. Dłuższe funkcje

należy podzielić na krótsze. W wyjątkowych przypadkach można zastosować dłuższą

funkcję – należy jednak mieć „mocne” uzasadnienie. Limit długości dotyczy również

programu głównego!

4.6 Klasy

4.6.1 Klasy powinny mieć ściśle określoną funkcjonalność. Należy unikać klas „do

wszystkiego”.

4.6.2 Składowe klasy należy deklarować w kolejności: publiczne, chronione, prywatne.

4.6.3 Klasa nie powinna zawierać publicznych atrybutów, chyba że jest to uzasadnione.

4.6.4 Deklaracja klasy i definicje jej metod powinny być osobno. Metody krótkie należy

definiować w tym samym pliku co deklaracja klasy (pod deklaracją klasy) jako

metody inline. Bardziej złożone metody należy definiować w osobnym pliku

(deklaracja klasy – plik nagłówkowy .h, definicje metod – plik implementacyjny .C).

4.6.5 Klasa nie powinna zawierać więcej niż 10 publicznych metod, chyba że jest to

uzasadnione (np. duża liczba atrybutów i konieczność dostarczenia metod

dostepowych).

5 Nazwy

5.1 Zasady ogólne

5.1.1 Do nazw identyfikatorów (stałe, zmienne, funkcje, klasy itd.) należy stosować

wyłącznie język angielski.

5.1.2 Nazwy powinny opisywać sens danego identyfikatora. Należy unikać nazw jedno-

znakowych. Wyjątkiem mogą być liczniki pętli (zwyczajowe nazwy i,j,k itd.).

5.1.3 Należy unikać kombinacji znaków o podobnym wyglądzie np. O i 0, l i 1 itp. Należy

unikać nazw trudnych do rozróżnienia np. aaa i aaaa. Należy unikać nazw

różniących się tylko wielkością liter.

5.1.4 W przypadku nazw złożonych z kilku słów należy używać zapisu „wielbłądziego” -

tzn. Każde kolejne słowo zaczynać od wielkiej litery, np. 'MojaKlasa', 'mojaFunkcja'

itd.

5.2 Nazwy zmiennych i stałych

5.2.1. Nazwy zmiennych powinny zaczynać się od małej litery.

5.2.2. Nazwy stałych powinny być pisane wielkimi literami.

5.2.3. Nazwy zmiennych wskaźnikowych powinny zawierać prefiks p. ('pCounter').

Plik z chomika:

Inne pliki z tego folderu:

Inne foldery tego chomika: