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
}

Change Log, czyli historia zmian kodu to fragment chronologicznie tworzonej dokumentacji (np. w postaci bloku komentarza), który służy po to by wskazać jakie zmiany (naprawione błędy lub nowe funkcjonalności) wprowadzono do kodu w jakiej wersji programu. Bardzo często będzie wynikać z użycia systemu wersjonowania kodu, np. GIT lub podobnego narzędzia do śledzenia zmian w projekcie.
Changelog formalnie nie ma określonej struktury, ani wskazanych informacji, które zawiera. Powinien jednak informować o:

• autorze zmian

• pliku/funkcji, której dotyczy zmiana

• wersja pliku

• opisie zmiany

• sygnatura zmiany (np. #13oc7b)

Changelog może składać się luźno z czterech głównych działań:

• [add] / [new] - Added, dodanie nowej funkcjonalności

• [mod] - Modification/Changed, zmiana istniejącej fukcjonalności, np. przepisanie, optymalizacja

• [deprec] - Depreciated, funkcjonalność planowana do usunięcia z bazy kodu programu/projektu

• [del] / [rem] - Deleted/Removed, usunięte z bazy kodu programu/projektu

• [fix] - Fixed, naprawione błędy w kodzie znalezione wcześniej

• [sec] - Security, zmiany w kodzie dot. bezpieczeństwa

Gdzie przechowywać w/w informacje o zmianach?

1. w pliku skryptu/programu - ChangeLog własny tegoż

2. w katalogu projektu - ChangeLog całego projektu

3. w historii commitów - ChangeLog całego projektu w systemie wersjonowania, np. GIT

Przykład komentarza/pliku Changelog

plik: code-changelog.php

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.