Programowanie/Podstawowe konstrukcje/Dokumentowanie

DokumetowanieEdytuj

Zalety starannego dokumentowania koduEdytuj

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 programuEdytuj

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 CEdytuj

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 dokumentacjiEdytuj

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.