Rozdział 7 - Metody - Dokumentowanie metod

Wiele nowoczesnych języków programowania udostępnia rodzaj komentarza, który możemy stosować w naszym kodzie do dokumentowania działania metod naszego programu. Komentarz taki zaczynamy od znaków /** a kończymy znakami */

Komentarze dokumentujące służą do:

  • pomocy w zrozumieniu działania metody,
  • opisie parametrów metody,
  • opisie zwracanej wartości,
  • informacji, czy metoda rzuca jakieś wyjątki i w jakich sytuacjach (o wyjątkach będziemy się uczyć wkrótce),
  • dodatkowo, można w komentarzu poinformować o m. in. autorze metody i wersji, od której jest dostępna.
Dokładny opis jak pisać komentarze tego typu można znaleźć na oficjalnej stronie firmy Oracle (właściciela języka Java): Jak dokumentować kod Java

Istnieją narzędzia, które potrafią przejść przez kod źródłowy naszego programu i wygenerować do niego dokumentację na podstawie komentarzy tego specjalnego typu. Przykładem takiego narzędzia jest oficjalny program do tworzenia dokumentacji dla języka Java o nazwie JavaDoc.

Wygenerowaną w ten sposób dokumentację możemy zobaczyć na np. oficjalnej stronie dokumentacji języka Java pod adresem:

JavaDoc - Dokumentacja Java

JavaDoc - dokumentacja typu String
Bardzo wiele frameworków, bibliotek itp. ma własne, wygenerowane w ten sposób dokumentacje dostępne w Internecie – programiści często z nich korzystają.

Spójrzmy na przykład użycia tego rodzaju komentarzy:

Nazwa pliku: JavaDocPrzyklad.java
import java.util.Scanner;

public class JavaDocPrzyklad {
  public static void main(String[] args) {
    System.out.println("Podaj liczbe");

    int x = getInt();

    System.out.println(
        "Ta liczba do kwadratu to " + policzKwadrat(x)
    );
  }

  /**
   * Metoda czeka na podanie przez uzytkownika wartosci,
   *  po czym ja zwraca.
   * @return Wartosc podana przez uzytkownika.
   */
  public static int getInt() {
    return new Scanner(System.in).nextInt();
  }

  /**
   * Zwraca przeslana liczbe podniesiona do kwadratu.

   * Przyklad: dla argumentu liczba rownego 5, zwroci 25.
   *
   * @param liczba Liczba, ktora chcemy podniesc do kwadratu.
   * @return Liczba podniesiona do kwadratu.
   */
  public static double policzKwadrat(int liczba) {
    return liczba * liczba;
  }
}

Przed metodami getInt oraz policzKwadrat znajdują się komentarze dokumentacyjne, opisujace co robi każda z tych metod. Dodatkowo, metoda policzKwadrat ma jeden argument, który opisujemy w następujący sposób: najpierw piszemy słowo param poprzedzone znakiem @ (małpa), po którym następuje nazwa argumentu, a po spacji jego opis (może on być dłuższy niż jedna linia).

Możemy w ten sposób opisać więcej, niż jeden parametr:

@param x Pozycja X.
@param y Pozycja Y.

Obie powyższe metody zwracają wartość – do opisu zwracanej wartości używamy słowa @return.

Jeżeli modyfikujemy czyjś kod, który ma komentarz dokumentacyjny, należy po wprowadzeniu zmian do metody zaktualizować także komentarz dokumentujący – jest to bardzo ważne, aby zachować spójność.

Pytanie: czy powinniśmy dokumentować wszystkie metody? Raczej nie – tylko te bardziej skomplikowane lub takie, których opis będzie przydatny w wygenerowanej dokumentacji, którą, być może, dostarczymy osobom, które będą korzystały z naszego kodu.

Dodaj komentarz

Twój adres email nie zostanie opublikowany.