Komentarz dokumentujący funkcję na egzaminie INF.04: wzór z listingu w C++, C#, Javie i Pythonie

W 16 z 21 arkuszy INF.04 z lat 2021-2026 część III („Dokumentacja aplikacji”) zaczyna się od polecenia: w kodzie źródłowym aplikacji konsolowej utwórz komentarz według wzoru z listingu 1. W pozostałych pięciu arkuszach część III to testy, a komentarza nie ma.

Klucz ocenia komentarz zwykle pięcioma kryteriami rezultatu 4 (R.4.1-R.4.5): komentarz zgodny z listingiem, nazwa i opis działania, nazwy i opisy parametrów, typ zwracany z opisem, numer zdającego. To 5 punktów za kilka linijek tekstu, każde kryterium za 1 punkt.

Przeczytaj pierwsze zdanie części III - arkusze różnią się tym, co trzeba opisać:

• dowolną funkcję lub metodę: INF.04-01-24.06-SG („wybranej”), INF.04-02-24.06-SG, INF.04-01-24.01-SG, INF.04-01-25.06-SG, INF.04-01-25.01-SG, INF.04-01-26.06-SG („jeden nagłówek do dowolnej funkcji / metody”),
• jedną metodę: INF.04-02-26.06-SG - klucz dodaje, że konstruktora nie traktuje się jako metody,
• wskazaną funkcję: przeszukującą (INF.04-01-22.06-SG), wypełniającą tablicę (INF.04-01-23.06-SG), wyznaczającą NWD (INF.04-01-23.01-SG), metodę klasy bazowej (INF.04-02-25.01-SG),
• dwie metody: sortującą i szukającą (INF.04-01-21.06-SG i ten sam arkusz w styczniu 2022) - klucz wymaga, żeby nagłówek miały obie,
• klasę: INF.04-03-23.06-SG, INF.04-02-23.01-SG, INF.04-02-24.01-SG (patrz krok o nagłówku klasy).

W większości arkuszy (INF.04-01-23.01-SG, INF.04-01-24.01-SG, INF.04-02-24.06-SG, INF.04-01-25.06-SG, INF.04-01-26.06-SG) wzór ma pięć pól. Tak wygląda w INF.04-01-26.06-SG:

nazwa funkcji:
<nazwa>
opis funkcji:
<opis co robi funkcja>
parametry:
<nazwa i opis parametru1, lub „brak”>
<nazwa i opis parametru2>
zwracany typ i opis: <nazwa typu i opis co jest zwracane lub „brak”>
autor: <numer zdającego>

Etykiety (nazwa funkcji:, opis funkcji:, parametry:...) przepisz dosłownie, a w miejsce nawiasów <> wpisz treść. Nawiasów nie zostawiaj.

Etykiety zmieniały się między sesjami. Przepisuj je z Twojego arkusza:

• INF.04-01-21.06-SG i INF.04-01-22.01-SG: nazwa funkcji, parametry wejściowe (nazwa - co przechowuje), wartość zwracana, autor (numer PESEL),
• INF.04-01-22.06-SG: nazwa funkcji, argumenty, typ zwracany, informacje, autor - w informacjach klucz wymaga przynajmniej nazwy algorytmu, np. „przeszukiwanie tablicy z wartownikiem”,
• INF.04-01-23.06-SG: nazwa funkcji, parametry wejściowe, wartość zwracana, informacje, autor - klucz podaje przykład „wyznaczenie liczb pierwszych, sito Eratostenesa”,
• INF.04-01-24.06-SG i INF.04-02-25.01-SG: nazwa, opis, parametry, zwracany typ i opis, autor,
• INF.04-01-25.01-SG: nazwa metody, opis metody, parametry, zwracany typ i opis, autor,
• INF.04-02-26.06-SG: nazwa, opis, parametry, zwracany typ, autor.

Kilka arkuszy pozwala napisać „metody” zamiast „funkcji”, gdy kod jest obiektowy (np. INF.04-02-24.06-SG, INF.04-01-25.06-SG, INF.04-01-26.06-SG).

Listing nie ma znaków początku i końca komentarza - arkusz wyjaśnia, że „te są różne dla różnych języków programowania”. Dopisujesz je sam: komentarz wieloliniowy (/* ... */ w C++, C# i Javie) albo kilka jednoliniowych (//, a w Pythonie #). Klucze od 2024 roku wymieniają też docstring Pythona (potrójny cudzysłów).

• Gwiazdki w ramce listingu nie są obowiązkowe: w styczniu 2023 arkusze piszą „liczba gwiazdek dowolna większa od 5”, od 2024 roku „liczba gwiazdek dowolna”, klucze - „nie należy brać pod uwagę liczby gwiazdek”, a listingi z czerwca 2026 nie mają ramki wcale.
• Miejsce: arkusze do 2023 roku każą umieścić nagłówek nad funkcją, od 2024 roku „nad lub pod nazwą funkcji”. Nad funkcją pasuje do obu wersji, a docstring Pythona z definicji stoi pod linią def.

Ta sama funkcja we wszystkich przykładach: NWD dwóch liczb algorytmem Euklidesa, z dwoma parametrami i wartością zwracaną. W C++ komentarz wieloliniowy /* ... */ stoi nad definicją funkcji:

#include <iostream>
using namespace std;

/**********************************************
 nazwa funkcji:
     nwd
 opis funkcji:
     wyznacza największy wspólny dzielnik dwóch liczb algorytmem Euklidesa
 parametry:
     a - pierwsza liczba całkowita dodatnia
     b - druga liczba całkowita dodatnia
 zwracany typ i opis: int - największy wspólny dzielnik liczb a i b
 autor: Bartosz Bryniarski
**********************************************/
int nwd(int a, int b)
{
    while (b != 0)
    {
        int reszta = a % b;
        a = b;
        b = reszta;
    }
    return a;
}

int main()
{
    cout << "NWD(12, 18) = " << nwd(12, 18) << endl;
    return 0;
}

Program skompilowany kompilatorem g++ wypisuje NWD(12, 18) = 6. W miejscu autora jest tu imię i nazwisko autora tutorialu - na egzaminie wpisujesz numer zdającego, czyli numer PESEL (albo numer paszportu), którym podpisany jest arkusz.

W C# nagłówek wygląda tak samo. Na zrzucie metoda CzyPoprawnaLiczbaKosci z przykładowego programu (rzut kośćmi, 3-10 kości) w Visual Studio 2022 - komentarz stoi nad metodą, a Visual Studio koloruje go na zielono:

/*
 nazwa funkcji:
     CzyPoprawnaLiczbaKosci
 opis funkcji:
     sprawdza, czy podana liczba kości mieści się w zakresie od 3 do 10
 parametry:
     liczba - liczba kości podana przez użytkownika
 zwracany typ i opis: bool - true, gdy liczba jest z zakresu 3..10, inaczej false
 autor: Bartosz Bryniarski
*/
public static bool CzyPoprawnaLiczbaKosci(int liczba)
{
    return liczba >= 3 && liczba <= 10;
}

Gdy w Visual Studio nad metodą wpiszesz ///, edytor sam wstawi szablon komentarza XML - na zrzucie nad metodą Rzuc(int liczba, Random los): <summary>, <param name="liczba">, <param name="los"> i <returns>. To dokumentacja w formacie .NET, ale nie wzór z arkusza - nie ma w nim etykiet nazwa funkcji:, opis funkcji: ani autor:.

W Javie metoda statyczna w klasie z metodą main. Komentarz /* ... */ nad metodą:

public class Nwd {

    /*
     nazwa funkcji:
         nwd
     opis funkcji:
         wyznacza największy wspólny dzielnik dwóch liczb algorytmem Euklidesa
     parametry:
         a - pierwsza liczba całkowita dodatnia
         b - druga liczba całkowita dodatnia
     zwracany typ i opis: int - największy wspólny dzielnik liczb a i b
     autor: Bartosz Bryniarski
    */
    static int nwd(int a, int b) {
        while (b != 0) {
            int reszta = a % b;
            a = b;
            b = reszta;
        }
        return a;
    }

    public static void main(String[] args) {
        System.out.println("NWD(12, 18) = " + nwd(12, 18));
    }
}

Program uruchomiony w JDK 21 wypisuje NWD(12, 18) = 6. Komentarz /** ... */ (Javadoc) też jest komentarzem wieloliniowym, ale etykiety wewnątrz muszą być takie jak w listingu, a nie znaczniki @param i @return.

W Pythonie najwygodniej użyć docstringu - napisu w potrójnym cudzysłowie zaraz pod linią def. Klucze od 2024 roku dopuszczają go wprost („w tym przypadku opis znajduje się pod nazwą funkcji”):

def nwd(a, b):
    """
    nazwa funkcji:
        nwd
    opis funkcji:
        wyznacza największy wspólny dzielnik dwóch liczb algorytmem Euklidesa
    parametry:
        a - pierwsza liczba całkowita dodatnia
        b - druga liczba całkowita dodatnia
    zwracany typ i opis: int - największy wspólny dzielnik liczb a i b
    autor: Bartosz Bryniarski
    """
    while b != 0:
        a, b = b, a % b
    return a


print("NWD(12, 18) =", nwd(12, 18))

Docstring nie jest zwykłym komentarzem - Python zapamiętuje go jako opis funkcji. Polecenie help(nwd) w IDLE pokazuje cały nagłówek, co jest szybkim sprawdzeniem, że stoi we właściwym miejscu.

Wzór z lat 2024-2026 każe w takich miejscach wpisać „brak”: <nazwa i opis parametru1, lub „brak”> i <nazwa typu i opis co jest zwracane lub „brak”>. Przykład dla metody, która tylko wypisuje menu:

/*
 nazwa funkcji:
     WypiszMenu
 opis funkcji:
     wypisuje w konsoli listę dostępnych poleceń programu
 parametry:
     brak
 zwracany typ i opis: void - brak, metoda nic nie zwraca
 autor: Bartosz Bryniarski
*/
static void WypiszMenu()
{
    Console.WriteLine("1 - rzut kośćmi, 0 - koniec");
}

Klucze INF.04-01-24.06-SG i INF.04-02-25.01-SG przyjmują przy braku wyniku „void, brak itp.”, inne - „brak”.

Trzy arkusze każą opisać klasę. Wzory są różne:

• INF.04-03-23.06-SG: nazwa klasy, pola (nazwa - co przechowuje), metody (nazwa, co zwraca - opis), informacje (co reprezentuje klasa), autor,
• INF.04-02-23.01-SG: klasa, opis (co klasa reprezentuje), pola („wpisz tyle pól ile ma klasa”), autor,
• INF.04-02-24.01-SG: klasa, opis (co klasa reprezentuje i wykonuje), metody (nazwa - co zwraca), autor.

Przykład według wzoru z INF.04-02-23.01-SG:

/*
 klasa: Kosc
 opis:
     reprezentuje jedną kość do gry i jej ostatnio wyrzuconą wartość
 pola:
     wartosc - liczba oczek wyrzucona w ostatnim rzucie
     los - generator liczb pseudolosowych używany do rzutu
 autor: Bartosz Bryniarski
*/
class Kosc
{
    private int wartosc;
    private Random los = new Random();
}

Sprawdź nagłówek z kodem i z arkuszem, punkt po punkcie:

1. Etykiety są takie jak w listingu Twojego arkusza, a nawiasy <> zastąpione treścią.
2. Opisana jest funkcja, której wymaga arkusz (albo dowolna - gdy arkusz na to pozwala).
3. Nazwa w komentarzu jest taka sama jak w kodzie, łącznie z wielkością liter.
4. Opisane są wszystkie parametry, a gdy ich nie ma - wpisane „brak”.
5. Typ zwracany ma nazwę i opis (np. int - największy wspólny dzielnik), a przy braku wyniku - „brak”.
6. W polu autora jest numer zdającego z pierwszej strony arkusza.
7. Program nadal się kompiluje - niedomknięty komentarz /* potrafi „zjeść” resztę kodu.
8. Plik źródłowy z komentarzem jest skopiowany do folderu aplikacji konsolowej (poza archiwum projektu), bo egzaminator czyta właśnie ten plik.