Programowanie/Podstawowe konstrukcje/Dokumentowanie

Z Wikibooks, biblioteki wolnych podręczników.
Przejdź do nawigacji Przejdź do wyszukiwania

Dokumetowanie[edytuj]

Zalety starannego dokumentowania kodu[edytuj]

W programowaniu bardzo ważne jest staranne dokumentowanie swojej pracy. Programowanie wymaga dyscypliny. Dobre programowanie wymaga wiele dyscypliny.

Często kod musi być wielokrotnie, przeglądany przez różne osoby w różnych celach np.:

  1. poszukiwanie błędów, weryfikacja poprawności
  2. próba rozmaitych usprawnień kodu
  3. inspekcja w celu zbadania jakości kodu

Dobrze udokumentowany projekt jest znacznie łatwiejszy w późniejszym utrzymaniu. Wkład pracy związany z tworzeniem dokumentacji zwraca się bardzo szybko. Znane są przypadki projektów, które upadły z powodu trudności z usunięciem błędów. Dobra dokumentacja pomaga w usprawnieniu kodu, lub jego nowszych wersji.

komentarze w kodzie programu[edytuj]

Z tego powodu w kodzie źródłowym programista może umieszczać komentarze. Komentarze są napisami o specjalnej składni. Są one ignorowane przez kompilator, stanowią natomiast cenną informację dla osób przeglądających kod programu.

Komentarze w języku C[edytuj]

W języku C istnieją dwa rodzaje komentarzy. Pierwszy rodzaj (starszy) polega na umieszczeniu tekstu komentarza pomiędzy napisami "/*" oraz "*/". Komentarz tego typu może zawierać wiele wierszy.

przykłady:

/* to jest komentarz. */

/*
To też komentarz.
W kilku liniach.
*/

/*
===== To także jest komentarz. Bardziej wytłuszczony =====
*/

/***********************************
*                                  *
* Bardzo wytłuszczony komentarz    *
*                                  *
************************************/

Drugi rodzaj komentarzy (zaczerpnięty z języka C++) rozpoczyna się znakami "//" i rozciąga do końca wiersza.

przykłady:

//to jest komentarz jednowierszowy

// komentowanie w wielu wierszach
// jest możliwe jedynie
// przez rozpoczynanie
// każdej linii komentarza
// znakami "//"

//==============================================================================
// graficzna separacja fragmentów kodu

Przykłady zastosowania komentarzy.

Lekki komentarz opisujący niewielki fragment kodu:

//tu będzie drobna operacja
wykonajDrobnaOperacje();

Większy komentarz na początku programu. Opisuje podstawowe informacje o programie. Generalnie przykład dla ilustracji, drobiazgowe informacje można podać w załączonej dokumentacji.

/*
* Program PODATEK DELTA
* wersja: 4.16.3
* autor: Jan Kowalski
* data: 03.03.2016
* jezyk programowania: C99
* kompilator: GNU gcc
* kompilacja: gcc main.c -o prog.out
* co program robi: Program oblicza podatek dochodowy dla osób fizycznych za rok 2016
* metoda obliczania: na Korwina (wypowiedz z dnia 12 lipca 2016r. w Parlamencie Europejskim, godz. 12:12 GMT -1)
* licencja: GNU General Public License v.3
* wykryte błędy: nie było reklamacji
*/

Stosowanie komentarzy będzie opisywane podczas nauki.

Narzędzia do tworzenia dokumentacji[edytuj]

Przy większych projektach dobrze jest ułatwić sobie przeglądanie kodu. Służą do tego automatyczne generatory dokumentacji. Przykładem jest darmowy generator Doxygen. Pozwala na wygodne i szybkie przeglądanie większych ilości kodu. Do celów edukacyjnych nie jest niezbędny. Zostanie opisany w dalszym ciągu nauki.