Która z dokumentacji funkcji odpowiada przedstawionemu kodowi źródłowemu? static int Abs(int liczba) { if (liczba < 0) liczba *= -1; return liczba; } Dokumentacja 1: /******************* * nazwa: Abs * opis: liczy wartość bezwzględną * zwracana: brak * argumenty: liczba całkowita *******************/ | Dokumentacja 2: /******************* * nazwa: Abs * opis: liczy wartość bezwzględną * zwracana: wartość bezwzględna z liczby całkowitej * argumenty: liczba całkowita *******************/ Dokumentacja 3: /******************* * nazwa: Abs * opis: liczy potęgę liczby * zwracana: potęga z liczby całkowitej * argumenty: dwie liczby całkowite *******************/ | Dokumentacja 4: /******************* * nazwa: Abs * opis: liczy potęgę liczby * zwracana: potęga z liczby całkowitej * argumenty: liczba całkowita *******************/

Wyjaśnienie

Dokumentacja 2 zdecydowanie najlepiej pasuje do przedstawionej funkcji. Zwróć uwagę, że sama definicja funkcji „Abs” w kodzie przyjmuje jeden argument typu całkowitego (int) i zwraca także liczbę całkowitą. Jej zadaniem jest zwrócenie wartości bezwzględnej tej liczby, co dokładnie opisuje fragment: „zwracana: wartość bezwzględna z liczby całkowitej”. To bardzo ważne, bo w programowaniu – a szczególnie w językach takich jak C# czy C++ – jasna i kompletna dokumentacja pozwala potem innym korzystać z funkcji bez konieczności zaglądania do jej wnętrza. W praktyce, takie szczegółowe opisywanie co zwraca dana funkcja i jakie przyjmuje argumenty, znacznie przyspiesza pracę w większych zespołach. Standardem branżowym jest właśnie precyzyjne określanie typu zwracanego i opisu działania, a nie tylko suchy komentarz typu „zwraca: brak” (co byłoby niezgodne z kodem!). Co ciekawe, w wielu firmach stosuje się rozbudowane systemy dokumentacji (np. Doxygen czy XML doc w .NET), które niejako wymuszają takie dokładne opisy. Osobiście uważam, że przyzwyczajenie się do dobrych praktyk dokumentowania funkcji już na etapie nauki procentuje w przyszłości – mniej pytań w zespole, mniej nieporozumień. Ta konkretna dokumentacja spełnia wszystkie kluczowe kryteria: podaje nazwę, precyzyjny opis, prawidłowy typ zwracanej wartości oraz właściwy typ i opis argumentu. Idealnie odzwierciedla, co robi ten fragment kodu, a to podstawa w pisaniu czytelnych i bezpiecznych aplikacji.