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 *******************/ |
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.
Każda z pozostałych dokumentacji zawiera poważne nieścisłości względem kodu funkcji „Abs”. W przypadku pierwszej dokumentacji kłopotliwa jest sekcja „zwracana: brak”, chociaż kod jasno pokazuje, że funkcja zwraca liczbę całkowitą – to wcale nie jest funkcja typu void, tylko int, więc nie da się tego rozumieć jako „brak zwracanej wartości”. To dość powszechny błąd, szczególnie na początku nauki: mylenie funkcji, które coś zwracają, z tymi, które wykonują operacje bez zwracania wyniku. W praktyce takie niedopasowanie między dokumentacją a kodem potrafi prowadzić do przykrych nieporozumień, a nawet błędów na etapie integracji. Dokumentacja trzecia i czwarta wpadają w kolejną pułapkę: opisują zupełnie inne działanie. Piszą o potęgowaniu (liczeniu potęgi liczby), podczas gdy funkcja Abs absolutnie nie zajmuje się potęgą – jej zadanie to wartość bezwzględna. Dodatkowo, dokumentacja trzecia błędnie twierdzi, że funkcja przyjmuje dwie liczby całkowite, co jest niezgodne z kodem – tam jest tylko jeden parametr. Takie pomieszanie pojęć często wynika z nieuważnego czytania specyfikacji lub mechanicznego kopiowania dokumentacji z innej funkcji. W branży takie rozbieżności są bardzo źle widziane, bo dokumentacja powinna być lustrzanym odbiciem kodu. Osobiście wiele razy widziałem projekty, w których błędna dokumentacja prowadziła do powielania bugów lub niepotrzebnych refaktoryzacji. Dobrym zwyczajem jest zawsze poświęcić chwilę na sprawdzenie, czy opis odpowiada faktycznemu działaniu kodu. Myślę, że ta sytuacja dobrze pokazuje, jak ważna jest precyzja – zarówno w kodowaniu, jak i dokumentowaniu.