Dokumentacja funkcji opisuje, do czego służy funkcja/metoda, jakie przyjmuje argumenty i co zwraca. W zadaniach egzaminacyjnych często trzeba porównać dokumentację z kodem źródłowym i wskazać opis zgodny z implementacją.
Co powinna zawierać dokumentacja?
Najczęściej opisuje się:
- nazwę funkcji,
- opis działania,
- argumenty/parametry funkcji,
- wartość zwracaną,
- czasem także typy danych i warunki szczególne.
Przykład
static int Abs(int liczba)
{
if (liczba < 0)
liczba *= -1;
return liczba;
}
Poprawna dokumentacja powinna informować, że funkcja:
- nazywa się Abs,
- przyjmuje jeden argument typu int,
- oblicza wartość bezwzględną,
- zwraca liczbę całkowitą będącą wartością bezwzględną argumentu.
Przykładowy poprawny opis:
nazwa: Abs
opis: liczy wartość bezwzględną
zwracana: wartość bezwzględna z liczby całkowitej
argumenty: liczba całkowita
Na co uważać?
Jeżeli funkcja ma typ zwracany inny niż void, to coś zwraca. W kodzie static int Abs(...) typ int oznacza, że funkcja zwraca liczbę całkowitą. Instrukcja return liczba; potwierdza, jaka wartość jest zwracana.