Komentarz (informatyka)

Komentarz – fragment kodu źródłowego, którego jedynym celem istnienia jest informowanie o czymś osoby czytającej źródła, a który nie ma żadnego wpływu na program – i jest zazwyczaj przez kompilator czy też interpreter pomijany.

Komentarz to typowy lukier składniowy.

Zasady stosowania komentarzy

Istnieją różne szkoły pisania komentarzy – od jednej skrajności, mówiącej, że z komentarzy powinno się móc wywnioskować wszystko, co program robi, bez oglądania reszty źródeł, do drugiej, mówiącej, że jeśli kod nie jest oczywisty bez komentarzy, to jest to zły kod, a komentarze są właściwie zbędne^[1].

Generalnie jednak wśród dobrych programistów panuje zgoda, iż jeśli pisze się komentarz, to komentowany powinien być powód, dla którego kod robi to, co robi, lub został napisany tak, a nie inaczej; nie powinien natomiast opisywać tego, co można z łatwością wyczytać – winien opisywać rzeczy, które nie są widoczne na pierwszy rzut oka, patrząc na dany kawałek źródeł. Komentarz również nie powinien być błędny, gdyż powoduje to problemy podczas sprawdzania i konserwacji kodu. Nie powinno się również używać komentarzy do prowadzenia notatek, a jeśli już jego prowadzenie jest potrzebne ze względu na długie tworzenie kodu komentarze powinno się usunąć po uzupełnieniu programu^[1].

Właściwość komentarzy polegająca na ich „niewidzialności” z punktu widzenia kompilatora jest szeroko wykorzystywana jako metoda rozszerzania właściwości języka. W sekcjach stanowiących komentarze zapisywane są dyrektywy dla kompilatora (pascal^[2][3]), treści dla parserów tworzących dokumentacje, czy wręcz całe procedury (JavaScript wewnątrz HTML^[4][5]).

Rodzaje komentarzy

Podział komentarzy w językach programowania można dokonać na podstawie różnych kryteriów:

• podział ze względu na sposób traktowania komentarzy przez translator
• podział ze względu na składnię.

Podział ze względu na interpretację

Komentarz (wraz ze znakami wydzielającymi komentarz z kodu źródłowego) mogą być traktowane przez translator:

• tak, jakby ich nie było, jako znak pusty (oznacza to możliwość wstawienia komentarza wewnątrz literału, np. wh{pętla}ile, przy czym napis ten przez translator zostanie uznany za napis while;
• tak, jak odstęp, np. tak jak spację, np. while{początek pętli}a<b do, komentarz traktowany jak spacja oddzieli słowo kluczowe while od identyfikatora a;
• tak, jak instrukcja pusta, np. REM w Basic-u^[6][7], choć komentarz jest ignorowany, to poprzedzony etykietą umożliwia skok do tego miejsca w programie;
• w inny określony przez implementację sposób.

Podział ze względu na składnię

Ze względu na składnię komentarze dzieli się na:

• blokowe,
• liniowe,
  • obejmujące całą linię,
  • obejmujące linię od określonego znaku/znaków do końca linii,
• inne, specjalne.

Komentarze blokowe charakteryzują się tym, że mają znak lub znaki otwierające komentarz i znak lub znaki zamykające komentarz, np. w języku C^[8][9][10]: znaki otwierające /* i znaki zamykające */. Daje to możliwość:

• umieszczania komentarzy wewnątrz linii kodu źródłowego (patrz wyżej);
• tworzenia komentarzy składających się z wielu linii tekstu bez konieczności poprzedzania każdej linii znakiem komentarza.

Komentarze liniowe to komentarze, które rozpoczynają się od określonego znaku/znaków, a kończą znakiem/znakami końca linii (np. znakiem o kodzie ASCII 13 lub parą znaków 13 i 10, albo innymi przyjętymi w danym systemie). Tworzenie komentarzy składających się z kilku linii wymaga poprzedzania wszystkich linii tekstu znakami komentarza. Rozróżnić można dwa przypadki:

• komentarzem musi być cała linia tekstu,
• komentarz rozpoczyna się w dowolnym miejscu linii kodu źródłowego od określonego znaku/znaków, a końcem komentarza jest koniec linii.

Przykład w języku Basic^[6][7]:

 10 REM To jest komentarz składający się z całej linii kodu źródłowego
 20 LET A=1 ' A to komentarz od znaku ' do końca linii

Zestawienie komentarzy

Komentarze w językach programowania

Język programowania	Rodzaj	Składnia
Assembler[11], AutoLISP	liniowy	; komentarz
ALGOL 60[12]	blokowy	begin comment [komentarz]; end;
	blokowy	comment [komentarz];
	blokowy	end komentarz <; lub end lub else>
	inny: w deklaracji i wywołaniu procedury	nazwa_proc(par1) [komentarz_2]:(par2) [komentarz_3]:(par3) ... [komentarz_n]:(par_n);
Bash	liniowy	# [komentarz]
Basic[6][7], Visual Basic[13][14]	liniowy	[nr linii] REM [komentarz]
	liniowy	[nr linii] [instrukcja] ' [komentarz]
PL/I[15][16], PL/M[17][18]	blokowy	/* [komentarz] */
C[8][9][10], C++[10], C#[19]	blokowy	/* [komentarz] */
	liniowy	// [komentarz]
Clipper[20]	liniowy1)	* [komentarz]
	liniowy	&& [komentarz]
	liniowy	// [komentarz]
DBase[21][22]	liniowy	[instrukcja] && [komentarz]
	liniowy1)	* [komentarz]
Fortran 77[23]	liniowy1)	C [komentarz]
	liniowy1)	* [komentarz]
Forth[24][25]	blokowy	( [komentarz] )
Icon[26], Perl[27]	liniowy	[instrukcje] # [komentarz]
Jean[28][29]	liniowy1)	* [komentarz]
Logo[30]	liniowy1)	; [komentarz]
Makefile (Borland)[3]	liniowy	[instrukcje] # [komentarz]
Modula 2[31]	blokowy	(* [komentarz] *)
Pascal[2][3]	blokowy	{ [komentarz] }
	blokowy	(* [komentarz] *)
Prolog[32]	liniowy	% komentarz
	blokowy	/* [komentarz] */
PHP[33]	liniowy	# [komentarz]
	liniowy	// [komentarz]
	blokowy	/* [komentarz] */
Python[34]	liniowy	[instrukcje] # [komentarz]
	blokowy	""" [komentarz] """
Simula 67[35]	blokowy	comment [komentarz];
Snobol[36]	liniowy1)	* [komentarz]
1) Znak komentarza musi być pierwszym znakiem w linii kodu:

Zestawienie według rodzajów

rodzaj	typ, uwagi	składnia	języki programowania
liniowy	cała linia, znak komentarza musi być pierwszym znakiem	* komentarz	Clipper[20], Cobol[37], DBase[21][22], Fortran 77[23], Snobol[36], Jean[28][29]
		C komentarz	Fortran 77[23]
		; komentarz	Logo[30]
	może być poprzedzony wyłącznie określoną jednostką leksykalną	[nr_linii] REM komentarz	Basic[6][7], Visual Basic[13][14]
	może być poprzedzony instrukcją/instrukcjami	[instr.] ' komentarz	Basic (niektóre dialekty), Visual Basic[13][14]
		[instr.] ; komentarz	Asembler[11], AutoLISP
		[instr.] // komentarz	C++[10], Clipper[20], JavaScript
		[instr.] && komentarz	Clipper[20], DBase[21][22]
		[instr.] % komentarz	Prolog[32]
		[instr.] # komentarz	Icon[26], Perl[27], Makefile (Borland)[3], Python
		[instr.] -- komentarz	SQL
blokowy	o zapisie swobodnym	{ komentarz }	Pascal[2][3]
		(* komentarz *)	Pascal, Modula 2[31], ML, Mathematica, AppleScript, Ocaml
		( komentarz )	Forth[24][25]
		/* komentarz */	C[8][9][10], C++[10], C♯, Java, JavaScript[4][5], PHP[38], SQL, Visual Prolog, CSS, PL/I[15][16], PL/M[17][18], Prolog[32]
		""" komentarz """	Python[34]
		instrukcja; comment komentarz; instrukcje ...	ALGOL 60[12], Simula 67[35]
		begin comment komentarz; instrukcje ... end; end komentarz <; | end | else>	ALGOL 60[12]
		<!--komentarz-->	Wiki, HTML, XML[a]
inne	opis parametrów podprogramów	nazwa_proc(par1) komentarz_2:(par2) komentarz_3:(par3) ... komentarz_n(par_n);	ALGOL[12] – można stosować w deklaracji i wywołaniu procedury