Komentarze oraz Adnotacje

Komentowanie pisanego kodu jest dobrą praktyką, którą należy stosować na bieżąco - zalety tego rozwiązania to:

• Opisywanie kroków, algorytmów, czy działania metod (jako wstęp do właściwej dokumentacji lub jako jedyna dokumentacja)

• Opisowa pomoc przy powracaniu do własnego kodu po dłuższej przerwie (np. po 3, 6, czy 12 miesiącach pracy nad innym projektem)

• Wsparcie innych programistów, którzy pomagają nam, przejmują kod lub dziedziczą projekt

• Zaznaczanie, co się dzieje z kodem: Nie działa ponieważ prawdopodobnie ..., Podczas akcji ... dzieje się ..., Skończono na kroku ... itp.

Rodzaje komentarzy w różnych językach

// komentarz 1-linijkowy zastosowanie: Java, PHP, JavaScript i kilka innych

# komentarz 1-linijkowy zastosowanie: Python, PHP i kilka innych

/* komentarz blokowy, inaczej wielolinijkowy */ zastosowanie: Java, PHP, JavaScript, CSS i kilka innych

''' komentarz blokowy dla dokumentacji, inaczej wielolinijkowy ''' zastosowanie: Python

Przykład zwykłych komentarzy

Prezentowany kod w języku JavaScript

let addTo = (e)=>{	// metoda obsługująca kliknięcie odnośnika:
	// - dodająca własną strukturę wpisu do Historii przeglądarki
	// - dodająca wpis odwiedzonej strony na własnej Historii w znaczniku SELECT
	e.preventDefault();	// wyłączenie obsługi domyślnego działania: adresacji wewnętrznej
	console.log(e.target.href); // efekt, np.: /home/gp/../js12-history-url/demo.html#docs
	let hash = null;	// attr href=""
	if( e.type='click' ){	// #TODO dlaczego znak = a nie == ? czy to błąd?
		hash = e.target.href.split('#')[1];	// z pełnego URL interesuje mnie tylko tzw. Fragment URL (#docs)
	} else { // obsługa Eventu: popstate
		hash = location.hash.replace('#','');	// pozbywam się zbędnego znaczka # (hashtag)
	}
	// wyszukaj odnośnik z atrybutem: data-ajax="hash"
	let label = document.querySelector('a[href="#'+hash+'"]');
	// jeżeli wchodzę ze strony głównej, to brak #etykiety
		label = (label===null) ? 'Home' : label.textContent;
	console.log(label+' #'+hash);	// efekt np.: Dokumentacja #docs
	// przy kliknięciu w odnośnik zmiana tytułu dokumentu znacznika TITLE
	updPageTitle(label);
	// ręcznie dopisz do historii (np. po zablokowaniu domyślnego Eventu)
	history.pushState(hash,label,'#'+hash);
	let len = barHistory.length;
	// dodaj do włąsnej tablicy Historii odwiedzanych stron nowy wpis
	barHistory[len] = { hashKey:hash, value:label };
		location.hash = hash;	// uaktualniam adres URL w pasku adresowym przeglądarki
	console.log(barHistory);	// sprawdzam zawartość tablicy
	// #TODO zaimplementować i wywołać metodę dodającą odwiedzony odnośnik do znacznika SELECT
}

Komentarz JavaDoc dla języka Java mieści się wewnątrz standardowego komentarza /* oraz */ jednak komentarz JavaDoc ma dodatkową gwiazdkę na począku: /**

1. Pierwszy akapit jest opisem dokumentowanej metody.
2. Następnie po opisie metody znajduje się różna ilość Tagów opisujących, np.:

   1. Parametry metody (@param)

   2. Co zwraca metoda (@return)

   3. Rzucane przez metodę wyjątki (@throws)

   4. Inne, mniej popularne tagi @see (np "see also" tag)

Przykładowy kod programu zawierający komentarze JavaDoc

/**
 * @author      Firstname Lastname <address @ example.com>
 * @version     1.6          (current version number of program)
 * @since       1.2          (the version of the package this class was first added to)
 */
import *;
public class AddNum {
   /**
   * This method is used to add two integers. This is
   * a the simplest form of a class method, just to
   * show the usage of various javadoc Tags.
   * @param numA This is the first paramter to addNum method
   * @param numB  This is the second parameter to addNum method
   * @return int This returns sum of numA and numB.
   */
   public int addNum(int numA, int numB) {
      return numA + numB;
   }

   /**
   * This is the main method which makes use of addNum method.
   * @param args Unused.
   * @return Nothing.
   * @exception IOException On input error.
   * @see IOException
   */
   public static void main(String args[]) throws IOException {
      AddNum obj = new AddNum();
      int sum = obj.addNum(10, 20);
      System.out.println("Sum of 10 and 20 is :" + sum);
   }
}

Źródło kodu: Portal Tutorials point

Wybrane TAG'i Adnotacji w Java.