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

Приклад коду Java, вступні коментарі багаторядкові розмальовані червоним, а однорядкові зеленим. Сам код програми синім.

У програмуванні, коментар це зрозуміла для програміста анотація в коді комп’ютерної програми. Їх пишуть для того щоб зробити сирцевий код більш зрозумілим, вони ігноруються при компіляції й інтерпретації. Запис коментарів сильно відрізняється в залежності від мови програмування.

Їх пишуть не тільки для роз’яснення вихідного коду програмістам, коментарі також обробляють різними способами для створення окремої документації на базі вихідного коду за допомогою генераторів документації, або використовують для інтеграції з системою контролю версій чи іншим інструментами програмування.

Щоб не було зловживань з використанням коментарів, у багатьох мовах для них виділені окремі розділи в рекомендаціях з оформлення коду.

Огляд

Коментарі зазвичай мають два формати: багаторядкові і однорядкові.

Багаторядкові коментарі у коді обмежуються роздільниками на початку і в кінці, всі символи всередині вважаються коментарем. Деякі мови програмування (наприклад MATLAB) дозволяють створювати вкладені коментарі, інші ні (наприклад Java).

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

Деякі мови програмування використовують обидва типи коментарів, але з різними роздільниками. Для прикладу, C++ має багаторядкові коментарі, які починаються з /* а закінчуються */ і однорядкові для яких використовується роздільник //. Інші мови підтримують тільки один тип коментарів. Для прикладу, Ada підтримують тільки однорядкові коментарі, роздільник --.

Використання

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

Планування і перевірка коду

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

/* 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")

Опис алгоритму

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

Для прикладу, тут програміст в коментарі може пояснити чому він вибрав сортування вставками замість звичного 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 графіки можуть бути вставлені в вихідний код, у вигляді коментаря. Також у них можна розмістити інформацію про авторське право. Бінарна інформація теж може бути записана у коментарях, завдяки перетворенню binary-to-text, хоча це рідко практикуються.

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

<!-- 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;
 // */

Автоматична генерація документації

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

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

Приклади

Ada

Мова програмування 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

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

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

-- Show the greeting
greet("Hello")

BASIC

Фрагмент коду на 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

Цей фрагмент коду на 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

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

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

Fortran IV

Цей код на 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 90

Цей код на 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

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

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

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

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

У цьому фрагменті коду на 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

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

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

MATLAB

У мові програмування 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

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

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

Pascal

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

Приклад:

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

Perl

Однорядкові коментарі в 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, приклад:

=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

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

PowerShell

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

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

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

Python

Коментарі в 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

Коментарі в 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

Коментарі в 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 також підтримує альтернативний формат коментарів. Підтримує багаторядковий стиль запису такий як в C++ і Java.

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

XML

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

<!--

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

-->

Для прикладу

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