Коментар (програмування)

Коментарі можуть бути використані для написання програми на псевдокоді і в подальшому на цій базі написання реального коду.

/* loop backwards through all elements returned by the server (they should be processed chronologically)*/
for (i = (numElementsReturned - 1); i >= 0; i--){
    /* process each element's data */
    updatePattern(i, returnedElements[i]);
}

Таке використання коментарів полегшує роботу тому хто робить перегляд коду, бо видно що планувалося зробити і що є насправді. Але такий метод коментування породжує очевидні коментарі, які засмічують код.

Коментарі можуть бути використанні для узагальнення чи пояснення намірів розробника, тобто описувати логіку програми. Прихильники даного підходу вважають поганою практикою писати коментарі безпосередньо до рядків коду, а також якщо саме код потребує додаткових пояснень це ознака занадто складного чи неякісного коду.

У коментарях також можна пояснювати виняткові ситуації (наприклад, код який не вписується в узгоджені правила розробки). Такі коментарі часто зустрічаються на ранніх етапах розробки чи зневадження. Для прикладу:

' Second variable dim because of server errors produced when reuse form data. No
' documentation available on server behavior issue, so just coding around it.
vtx = server.mappath("local settings")

Іноді вихідний код містить специфічне рішення конкретної проблеми. У таких випадках коментарі можуть містити пояснення чому був вибраний саме такий розв'язок. Такі пояснення можуть включати в себе схеми і формальні математичні докази. Це може бути пояснення коду, а не роз'яснення того що ви хотіли зробити; для підтримки бази коду вони можуть відігравати вирішальну роль. Такі коментарі особливо рекомендується використовувати у вузькоспеціалізованих проблемних галузях або для спосіб оптимізації чи конструкцій, які рідко використовуються.[9]

Для прикладу, тут програміст в коментарі може пояснити чому він вибрав сортування вставками замість звичного quicksort, хоч перший, теоретично, повільніший ніж другий. Це можна було б описати так:

 list = [f (b), f (b), f (c), f (d), f (a), ...];
 // Need a stable sort. Besides, the performance really does not matter.
 insertion_sort (list);

Логотипи, діаграми та блок-схеми на базі ASCII графіки можуть бути вставлені в вихідний код, у вигляді коментаря.[10] Також у них можна розмістити інформацію про авторське право. Бінарна інформація теж може бути записана у коментарях, завдяки перетворенню binary-to-text, хоча це рідко практикуються.

Наведений далі код це фрагмент простої ASCII діаграми, яка зображує процес для скрипту системного адміністратора який міститься в Windows Script File виконається під Windows Script Host. Хоча в коді дана діаграма маркована як коментар, сама схема насправді буде відображатися в XML CDATA секції, яка технічно відрізняється від коментарів, але може виконувати аналогічну функцію.[11]

<!-- begin: wsf_resource_nodes -->
<resource id="ProcessDiagram000">
<![CDATA[
 HostApp (Main_process)
    |
    V
script.wsf (app_cmd) --> ClientApp (async_run, batch_process)
                |
                |
                V
         mru.ini (mru_history)   
]]>
</resyntaxhighlight>

Коментарі в комп'ютерній програмі можуть містити метадані про файл програми.

Зокрема, багато розробників які супроводжують ПЗ додають вступну довідку (в коментарях), для людей які планують читати вихідний код чи тим хто планує відправляти свої покращення.

Часто розробники записують у коментарі сніпети, які місця логіку для зневадження програми ці коментарі можна у будь-який момент розкоментувати і отримати інформацію про роботу програми. Також програмісти практикують коментування код при пошуку ділянки, яка некоректно працює. Приклад, відлагодження коду шляхом коментування:

 if (opt.equals ("e"))
   opt_enabled = true;
 /*
  if (opt.equals ("d"))
   opt_debug = true;
 // */
 //*
 if (opt.equals ("v"))
    opt_verbose = true;
 // */

Інструменти програмування іноді зберігають документацію і метадані в коментарях.[12] Вони можуть вказувати на включення заголовних файлів, інформацію про режим підсвітки тексту,[13] чи версію файлу.[14] Такі функціональні коментарі зазвичай наживають анотацією. Ведення документації у коментарях вихідного коду розглядається, як один із способів, щоб спростити процес підготовки документації, а також збільшити ймовірність того, що документація буде постійно оновлюватися зі змінами в коді.[15]

Програми генератори документації існують у багатьох мовах, наприклад: Java має Javadoc,  D Ddoc, Doxygen генерує документації для таких мов C, C++, Java, IDL, а PHPDoc для PHP.

Мова програмування Ada використовує '--' для позначення початку однорядкового коментаря.

Приклад:

  -- the air traffic controller task takes requests for takeoff and landing
   task type Controller (My_Runway: Runway_Access) is
      -- task entries for synchronous message passing
      entry Request_Takeoff (ID: in Airplane_ID; Takeoff: out Runway_Access);
      entry Request_Approach(ID: in Airplane_ID; Approach: out Runway_Access);
   end Controller;

Наступний код AppleScript показує два типи коментарів, які доступні у цій мові.

(*
This program displays a greeting.
*)
on greet(myGreeting)
     display dialog myGreeting & " world!"
end greet

-- Show the greeting
greet("Hello")

Фрагмент коду на BASIC повністю консольна програма, в якій використовується ключове слово REM ("REMark"), щоб додавати коментарі, які описують те, що робить програма.

10 REM This BASIC program shows the use of the PRINT and GOTO statements.
15 REM It fills the screen with the phrase "HELLO"
20 PRINT "HELLO"
30 GOTO 20

Весь текст після символу ' (апостроф) вважається коментарем у Microsoft BASICs, включно QuickBasic, Qbasic, Visual Basic, Visual Basic .NET і VBScript - і похідних таких як FreeBASIC і Gambas. Приклад на Visual Basic .NET:

Public Class Form1
    Private Sub Button1_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button1.Click
        ' The following code is executed when the user
        ' clicks the button in the program's window.

        MessageBox.Show("Hello, World") 'Show a pop-up window with a greeting
    End Sub
End Class

Цей фрагмент коду на C демонструє використання багаторядкових коментарів, щоб описати призначення умовного оператора. Коментар пояснює основні терміни і поняття, і включає підпис програмістом, який є автором коду.

 /*
  * Check if we are over our maximum process limit, but be sure to
  * exclude root. This is needed to make it possible for login and
  * friends to set the per-user process limit to something lower
  * than the amount of processes root is running. -- Rik
  */
 if (atomic_read(&p->user->processes) >= p->rlim[RLIMIT_NPROC].rlim_cur
     && !capable(CAP_SYS_ADMIN) && !capable(CAP_SYS_RESOURCE))
     goto bad_fork_free;

У C99, також стало можливо використовувати // синтаксис від C ++, для написання однорядкових коментарів.

ColdFusion використовує коментарі схожі до HTML коментарів, але замість двох дефісів, він використовує три. Ці коментарі зчитуються рушієм ColdFusion, а також не відображаються у браузері.

 <!--- This prints "Hello World" to the browser. --->
 <cfoutput>
   Hello World<br />
 </cfoutput>

Цей код на Fortran IV демонструє використання коментарів у цій мові.

C
C Lines that begin with 'C' (in the first or 'comment' column) are comments
C 
         WRITE (6,10)
      10 FORMAT(12H HELLO WORLD)
         END

Цей код на Fortran демонструє використання коментарів у цій мові.

!* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
!* All characters after an exclamation mark are considered as comments *
!* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
program comment_test
    print '(A)', 'Hello world' ! Fortran 90 introduced the option for inline comments.
end program

Однорядкові коментарі в Haskell починаються з '--' (два мінуси), а багаторядкові коментарі починаються з '{-' та закінчуються '-}'.

{- this is a comment
on more lines -}
-- and this is a comment on one line
putStrLn "Wikipedia"

Haskell також підтримує literate programming метод коментарів який відомий як "Bird Style". У такому коді всі рядки які починаються з > інтерпретуються, всі інші коментарі. Ще одна вимога полягає в тому, що ви завжди маєте залишати порожній рядок до і після блоку коду:

In Bird-style you have to leave a blank before the code.
 
> fact :: Integer -> Integer
> fact 0 = 1
> fact n = n * fact (n-1)
 
And you have to leave a blank line after the code as well.

У цьому фрагменті коду на Java показаний запис багаторядкових коментарів, для опису методу  setToolTipText. Стиль сумісний з стандартом Sun Microsystems Javadoc. Коментар призначений для зчитування процесором Javadoc.

 /**
  * Registers the text to display in a tool tip.   The text 
  * displays when the cursor lingers over the component.
  *
  * @param text  the string to display.  If the text is null, 
  *              the tool tip is turned off for this component.
  */
 public void setToolTipText(String text) {

JavaScript використовує // для однорядкових коментарів, /* */ для багаторядкових.

// A single line JavaScript comment
var iNum = 100;
var iTwo = 2; // A comment at the end of line
/*
multi-line 
JavaScript comment
*/

У мові програмування MATLAB, символ '%' вказує на однорядковий коментар. Багаторядкові коментарі доступні в конструкції між %{ і %}.

% These are the derivatives for each term
d = [0 -1 0];

%{
  %{
    (Example of a nested comment, indentation is for cosmetics (and ignored).)
  %}
  We form the sequence, following the Taylor formula.
  Note that we're operating on a vector.
%}
seq = d .* (x - c).^n ./(factorial(n))

% We add-up to get the Taylor approximation
approx = sum(seq)

OCaml використовує наступні багаторядкові коментарі.

codeLine(* comment level 1(*comment level 2*)*)

У сімействі мов Pascal Ніклауса Вірта (в тому числі Modula-2 та Oberon), коментарі відкриваються '(*' і завершуються '*)'.

Приклад:

(* test diagonals *)
columnDifference := testColumn - column;
if (row + columnDifference = testRow) or
    .......

Однорядкові коментарі в Perl, і багатьох інших скриптових мовах, починаються з символу решітка (#). Коментар на початку називається шебанг, вказує системі, як інтерпретувати код.

#!/usr/bin/perl
my $s = "Wikipedia"; # Sets the variable s to "Wikipedia".
print $s . "\n";     # Add a newline character after printing for shells that do not do so automatically.

Замість звичної конструкції, Perl використовує Plain Old Documentation, приклад:[16]

=item Pod::List-E<gt>new()

Create a new list object. Properties may be specified through a hash
reference like this:

  my $list = Pod::List->new({ -start => $., -indent => 4 });

See the individual methods/properties for details.

=cut

sub new {
    my $this = shift;
    my $class = ref($this) || $this;
    my %params = @_;
    my $self = {%params};
    bless $self, $class;
    $self->initialize();
    return $self;
}

Коментарі в PHP можуть бути або в стилі C ++ (як однорядкові так і багаторядкові), або використовувати хеш. PHPDoc стиль запозичений з Javadoc та є стандартом для документування PHP коду.

Коментарі в Windows PowerShell

# Single line comment
Write-Host "Hello, World!"

<# Multi
   Line
   Comment #>
Write-Host "Goodbye, world!"

Коментарі в Python використовують символ решітка. Нижче наведений приклад починається з #! вказує операційній системі, як інтерпретувати файл.

#!/usr/bin/env python

print("Hello World!") # this program prints "Hello World" to the screen and then quits.

Python також підтримує docstrings, спеціальний вид коментарів, які обрамляються у потрійні лапки  (''').

def foo(x, y):
    '''Frobnicate the bar and baz 
       together with one another'''
    return frob(frob(x), frob(y))

Коментарі в Ruby.

Однорядкові коментарі: (починається з "#")

puts "This is not a comment"

#this is commented

puts "This is not a comment"

Багаторядкові: (коментар записується між двома ключовими словами "begin" і "end")

puts "This is not a comment"

=begin

whatever goes in here

will be ignored

=end

puts "This is not a comment"

Коментарі в SQL доступні тільки однорядкові, відриваються двома знаками мінус:

-- This is a single line comment
-- followed by a second line
SELECT COUNT(*) 
       FROM Authors
       WHERE Authors.name = 'Smith'; -- Note: we only want 'smith'
                                     -- this comment appears after SQL code

Синтаксис Transact-SQL також підтримує альтернативний формат коментарів.[17] Підтримує багаторядковий стиль запису такий як в C++ і Java.

/*
This is a comment line 1
This is a comment line 2
*/
SELECT COUNT(*)
       FROM Authors

Коментарі в XML (або HTML) починаються з

<!--

і можуть розтягнутися на декілька рядків до закриваючої конструкції 

-->

Для прикладу

<!-- select the context here -->
<param name="context" value="public"/>