توضیح (برنامه‌نویسی رایانه‌ای)

توضیح یا کامِنت (به انگلیسی: Comment) متنی جهت گزارمان در کد منبع است که اجرا نمی‌شود. توضیح‌ها متن‌های جهت افزایش خوانایی کد منبع هستند که توسط مفسرها و کامپایلرها اجرا نمی‌شوند.^[1][2]

یک کد منبع جاوا که توضیحات در کامپایلر به رنگ قرمز و سبز مشخص شده‌اند.

تعریف

متن‌هایی هستند که برنامه نویسان در میان کدها می‌نویسند، اما آن متن‌ها به همراه کد اجرا نخواهند شد و تنها در میان کدها دیده می‌شوند و در خروجی برنامه نیز هیچ اثری از آنها نیست. هدف از استفاده از توضیحات، بالابردن خوانایی و تشخیص نقش کدهای نوشته شده توسط برنامه‌نویس، برای دیگران است.^[3]

کاربرد

هنگامی کد منبع از چندین خط تشکیل شده باشد یا اینکه زمان زیادی از کدنویسی آن پروژه گذشته باشد، خود به خود برنامه‌نویس ساختار کدنویسی خود را فراموش می‌کند. در این شرایط، اگر برنامه‌نویس، توضیحاتی در مورد ساختار و عملکرد کدها نوشته باشد، تنها با خواندن آن توضیحات، می‌تواند دوباره ساختار را به راحتی درک کند یا همچنین زمانی که برنامه‌نویس قصد دارد کدهای خود را در اختیار یک برنامه‌نویس دیگر قرار دهد، با نوشتن توضیحات در کدهایش، درک کدها را برای برنامه‌نویس دیگر بسیار ساده‌تر می‌کند.

انواع

در زبان‌های سی، سی++، جاوا، سی شارپ و جاوااسکریپت توضیحات را می‌توانیم به دو صورت تک خطی و چند خطی بنویسیم.

• توضیحات تک خطی (Inline comments): می‌توان توضیحاتی در یک خط نوشت.

Symbol	Languages
C	Fortran I to Fortran 77 (C in column 1)
REM	BASIC, Batch files
::	Batch files, COMMAND.COM, cmd.exe
NB.	J; from the (historically) common abbreviation Nota bene, the Latin for "note well".
⍝	APL; the mnemonic is the glyph (jot overstruck with shoe-down) resembles a desk lamp, and hence "illuminates" the foregoing.
#	Bourne shell and other UNIX shells, Cobra, Perl, Python, Ruby, Seed7, Windows PowerShell, PHP, R, Make, Maple, Elixir, Julia, Nim[4]
%	TeX, Prolog, MATLAB,[5] Erlang, S-Lang, Visual Prolog, PostScript
//	ActionScript, C (C99), C++, C#, D, F#, Go, Java, JavaScript, Kotlin, Object Pascal (Delphi), Objective-C, PHP, Rust, Scala, SASS, Swift, Xojo
'	Monkey, Visual Basic, VBScript, Small Basic, Gambas, Xojo
!	Fortran, Basic Plus, Inform, Pick Basic
;	Assembly x86, AutoHotkey, AutoIt, Lisp, Common Lisp, Clojure, Rebol, Red, Scheme
--	Euphoria, Haskell, SQL, Ada, AppleScript, Eiffel, Lua, VHDL, SGML, PureScript, Elm
*	Assembler S/360 (* in column 1), COBOL I to COBOL 85, PAW, Fortran IV to Fortran 77 (* in column 1), Pick Basic, GAMS (* in column 1)
||	Curl
"	Vimscript, ABAP
\	Forth
*>	COBOL 90

• توضیحات چندخطی (Block comments): می‌توان توضیحاتی در چند خط نوشت.

Symbol	Languages
comment ~ ;	ALGOL 60, SIMULA
¢ ~ ¢, # ~ #, co ~ co, comment ~ comment	ALGOL 68[6][7]
/* ~ */	ActionScript, AutoHotkey, C, C++, C#, D,[8] Go, Java, JavaScript, kotlin, Objective-C, PHP, PL/I, Prolog, Rexx, Rust (can be nested), Scala (can be nested), SAS, SASS, SQL, Swift (can be nested), Visual Prolog, CSS
#cs ~ #ce	AutoIt[9]
/+ ~ +/	D (can be nested)[8]
/# ~ #/	Cobra (can be nested)
<# ~ #>	Powershell
<!-- ~ -->	HTML, XML
=begin ~ =cut	Perl
#`( ~ )	Raku (bracketing characters can be (), <>, {}, [], any Unicode characters with BiDi mirrorings, or Unicode characters with Ps/Pe/Pi/Pf properties)
=begin ~ =end	Ruby
#<TAG> ~ #</TAG>, #stop ~ EOF, #iffalse ~ #endif, #ifntrue ~ #endif, #if false ~ #endif, #if !true ~ #endif	S-Lang[10]
{- ~ -}	هسکل (can be nested)
(* ~ *)	Delphi, ML, Mathematica, Object Pascal, Pascal, Seed7, Applescript, OCaml (can be nested), Standard ML (can be nested), Maple, Newspeak, F#
{ ~ }	Delphi, Object Pascal, Pascal, Red
{# ~ #}	Nunjucks, Twig
{{! ~ }}	Mustache, Handlebars
{{!-- ~ --}}	Handlebars (cannot be nested, but may contain {{ and }})
|# ~ #|	Curl
%{ ~ %}	MATLAB[11] (the symbols must be in a separate line)
#| ~ |#	Lisp, Scheme, Racket (can be nested in all three).
#= ~ =#	جولیا[12]
#[ ~ ]#	Nim[13]
--[[ ~ ]], --[=[ ~ ]=], --[=...=[ ~ ]=...=]	Lua (brackets can have any number of matching = characters; can be nested within non-matching delimiters)
" ~ "	اسمال‌تاک
(comment ~ )	کلوژر

مثال

برای مثال کد منبع زبان جاوااسکریپت در زیر، از دو نوع توضیحات استفاده کرده‌است:

/*
پروژه
اول من
*/
document.write("Hello, World!"); // در خروجی متن داخل دابل کوتیشن چاپ می‌شود

جستارهای وابسته

• حساسیت موردی
• برنامه‌نویسی ادیبانه

منابع

1. Source code can be divided into program code (which consists of machine-translatable instructions); and comments (which include human-readable notes and other kinds of annotations in support of the program code).Penny Grubb, Armstrong Takang (2003). Software Maintenance: Concepts and Practice. World Scientific. pp. 7, plese start120–121. ISBN 978-981-238-426-3.
2. For purposes of this article, programming language comments are treated as indistinct from comments that appear in markup languages, configuration files and other similar contexts. Moreover, markup language is often closely integrated with programming language code, especially in the context of code generation. See e.g. , Ganguli, Madhushree (2002). Making Use of Jsp. New York: Wiley. ISBN 978-0-471-21974-3., Hewitt, Eben (2003). Java for Coldfusion Developers. Upper Saddle River: Pearson Education. ISBN 978-0-13-046180-3.
3. جاوا اسکریپت به زبان ساده (PDF).
4. "Nim Manual".
5. "Mathworks.com". Archived from the original on 21 November 2013. Retrieved 25 June 2013.
6. "Algol68_revised_report-AB.pdf on PDF pp. 61–62, original document pp. 121–122" (PDF). Retrieved 27 May 2014.
7. "HTML Version of the Algol68 Revised Report AB". Archived from the original on 17 March 2013. Retrieved 27 May 2014.
8. "DLang.org, Lexical". Retrieved 27 May 2014.
9. "AutoItScript.com Keyword Reference, #comments-start". Retrieved 27 May 2014.
10. "slang-2.2.4/src/slprepr.c – line 43 to 113". Retrieved 28 May 2014.
11. "Mathworks.com". Archived from the original on 21 November 2013. Retrieved 25 June 2013.
12. "Punctuation · The Julia Language".
13. "Nim Manual".