Co to jest dokumentacja kodu?
Dokumentacja kodu to opis działania programu przygotowany dla programistów, którzy tworzą, rozwijają lub utrzymują aplikację. W projekcie zespołowym jest szczególnie ważna, ponieważ pozwala innym osobom szybko zrozumieć, jak działa dana część aplikacji.
Co może obejmować dokumentacja kodu?
Dokumentacja kodu może zawierać:
- komentarze wyjaśniające trudniejsze fragmenty kodu,
- opis funkcji, metod i klas,
- informacje o parametrach i wartościach zwracanych,
- opis struktury projektu,
- instrukcję uruchomienia aplikacji,
- opis zależności i konfiguracji środowiska,
- przykłady użycia wybranych funkcji.
Przykład dokumentacji funkcji
/**
* Dodaje zdjęcie do galerii.
*
* @param path ścieżka do pliku graficznego
* @return true, jeśli zdjęcie zostało dodane poprawnie
*/
boolean dodajZdjecie(String path) {
// kod funkcji
}
Dlaczego dokumentacja jest zadaniem zespołu?
W aplikacji tworzonej zespołowo różni programiści odpowiadają za różne moduły. Dokumentacja powinna być spójna i aktualna w całym projekcie, dlatego zespół powinien ustalić wspólne zasady jej tworzenia. Każdy członek zespołu dokumentuje swoją część kodu, ale całość powinna być kontrolowana wspólnie, np. podczas przeglądu kodu.
Na egzaminie
Jeśli pytanie dotyczy działania realizowanego przez zespół, dokumentacja kodu jest dobrym przykładem, bo wspiera współpracę, utrzymanie aplikacji i przekazywanie wiedzy między członkami projektu.