Jak korzystać z komentarzy w kodzie Java

Komentarze Java to uwagi w pliku kodu Java, które są ignorowane przez kompilator i silnik wykonawczy. Służą do opisywania kodu w celu wyjaśnienia jego projektu i celu. Możesz dodać nieograniczoną liczbę komentarzy do pliku Java, ale są pewne „najlepsze praktyki”, których należy przestrzegać podczas korzystania z komentarzy.

Zasadniczo komentarze do kodu są komentarzami „implementacyjnymi”, które wyjaśniają kod źródłowy, takie jak opisy klas, interfejsów, metod i pól. Zazwyczaj jest to kilka wierszy napisanych powyżej lub obok kodu Java, aby wyjaśnić, co robi.

Innym rodzajem komentarza Java jest komentarz Javadoc. Komentarze Javadoc różnią się nieznacznie składnią od komentarzy dotyczących implementacji i są używane przez program javadoc.exe do generowania dokumentacji Java HTML.

Dlaczego warto korzystać z komentarzy Java?

Dobrą praktyką jest przyzwyczajenie się do umieszczania komentarzy Java w kodzie źródłowym, aby zwiększyć jego czytelność i przejrzystość dla siebie i innych programistów. Nie zawsze jest od razu jasne, co wykonuje sekcja kodu Java. Kilka linii wyjaśniających może drastycznie skrócić czas potrzebny na zrozumienie kodu.

instagram viewer

Czy wpływają one na działanie programu?

Komentarze na temat implementacji w Kod Java są tylko dla ludzi do czytania. Kompilatory Java nie dbają o nie i kiedy kompilacja programu, po prostu je omijają. Na ilość komentarzy w kodzie źródłowym nie ma wpływu na rozmiar i wydajność skompilowanego programu.

Komentarze na temat realizacji

Komentarze dotyczące implementacji są dostępne w dwóch różnych formatach:

Komentarze do linii: W przypadku komentarza o jednym wierszu wpisz „//” i postępuj zgodnie z dwoma ukośnikami z komentarzem. Na przykład:
```
 // to jest komentarz jednowierszowy
int guessNumber = (int) (Math.random () * 10); 
```
Gdy kompilator natrafi na dwa ukośniki, wie, że wszystko po ich prawej stronie należy traktować jako komentarz. Jest to przydatne podczas debugowania fragmentu kodu. Po prostu dodaj komentarz z linii debugowanego kodu, a kompilator go nie zobaczy:
- ```
 // to jest komentarz jednowierszowy
// int guessNumber = (int) (Math.random () * 10); 
```
  Możesz także użyć dwóch ukośników, aby dodać komentarz na końcu linii:
- ```
 // to jest komentarz jednowierszowy
int guessNumber = (int) (Math.random () * 10); // Komentarz na końcu wiersza 
```
Blokuj komentarze: Aby rozpocząć komentarz do bloku, wpisz „/ *”. Wszystko między ukośnikiem i gwiazdką, nawet jeśli znajduje się w innym wierszu, jest traktowane jako komentarz, dopóki znaki „* /” nie zakończą komentarza. Na przykład:
```
 / * to 
jest 
za
blok
komentarz
*/
/ * więc to jest * /
```

Komentarze Javadoc

Użyj specjalnych komentarzy Javadoc do udokumentowania interfejsu API Java. Javadoc to narzędzie zawarte w JDK, które generuje dokumentację HTML na podstawie komentarzy w kodzie źródłowym.

Komentarz Javadoc w

.Jawa

pliki źródłowe są zawarte w składni początkowej i końcowej tak:

/**

*/

. Każdy komentarz w nich poprzedzony jest znakiem

Umieść te komentarze bezpośrednio nad metodą, klasą, konstruktorem lub innym elementem Java, który chcesz udokumentować. Na przykład:

// myClass.java
/**
* Niech to będzie zdanie podsumowujące opisujące twoją klasę.
* Oto kolejna linia.
*/
publicznyklasa moja klasa
{
...
}

Javadoc zawiera różne tagi, które kontrolują sposób generowania dokumentacji. Na przykład

@param

Tag definiuje parametry metody:

 / ** główna metoda
* @param argumentuje Ciąg []
*/
publicznystatycznyunieważnić main (Argumenty String [])
{
System.out.println („Hello World!”);
}

Wiele innych znaczników jest dostępnych w Javadoc, a także obsługuje znaczniki HTML, aby pomóc kontrolować dane wyjściowe. Więcej informacji znajduje się w dokumentacji Java.

Wskazówki dotyczące korzystania z komentarzy

Nie przesadzaj z komentarzem. Nie trzeba wyjaśniać każdej linii Twojego programu. Jeśli Twój program przepływa logicznie i nie dzieje się nic nieoczekiwanego, nie czuj potrzeby dodawania komentarza.
Wcinaj komentarze. Jeśli linia komentowanego kodu jest wcięta, upewnij się, że twój komentarz pasuje do wcięcia.
Trzymaj komentarze istotne. Niektórzy programiści doskonale modyfikują kod, ale z jakiegoś powodu zapomnij zaktualizować komentarze. Jeśli komentarz nie ma już zastosowania, zmodyfikuj go lub usuń.

Nie zagnieżdżaj komentarzy blokowych. Następujące spowoduje błąd kompilatora:

 / * to 
jest
/ * Ten komentarz blokowy kończy pierwszy komentarz * /
za
blok
komentarz
*/