Java iturburu-kodearen ilustrazioa, gorriz adierazitako hitzaurreko iruzkinekin eta berdezko lerro-iruzkinekin. **Programaren kodea** urdinez dago.
Programazio informatikoan, **ohar** edo **iruzkin** bat programak programa informatiko baten iturburu-kodean irakur dezakeen azalpen edo *ohar* bat da. Gizakientzako iturburu-kodea errazago ulertzeko eransten dira, eta, normalean, konpilatzaileek eta interpreteek enoratu egiten dituzte, ez-ikusiarena egiten dute ohar horiekin. Programazio-lengoaiaren arabera iruzkinak markatzeko moduak asko aldatzen dira.

Iruzkinak, halaber, zenbait modutan prozesatzen dira, batzuetan, iturburu-kodetik kanpoko dokumentazioa sortzeko, dokumentazio-sortzaileen bidez, edo iturburu-kodeak kudeatzeko sistemekin eta programazioko beste tresna batzuekin integratzeko ere erabiltzen dira.

Iruzkinek eskaintzen duten malgutasunak aldagarritasun-maila handia ahalbidetzen du, baina hori erabiltzeko konbentzio formalak programazio-estiloaren gidetan sartzen dira.

Adibideak
---------

Iruzkinak zehazteko konbentzio tipografikoak asko aldatzen dira programazio legoaiatan. 

#### Ada

Ada programazio-lengoaiak '--' erabiltzen du lerroaren amaierara arteko iruzkin bat adierazteko.

Adibidez:

```
  -- 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;

```

#### BASIC

Hasierako BASIC kode-zati klasiko honetan, REM gako-hitza ("Remark") oharrak gehitzeko erabiltzen zen.

```
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

```

#### C

C kodearen zati honek atariko iruzkin bat edo "bloke-iruzkin" bat erabiltzen du baldintzapeko adierazpen baten xedea deskribatzeko. Iruzkinak termino eta kontzeptu nagusiak azaltzen ditu, eta kodea idatzi zuen programatzailearen sinadura labur bat ere badu.

```
 /\*
 \* 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;

```

#### Haskell

Haskellen lerro-iruzkinak (erdiko bi marrekin ('--') hasten dira lerroaren amaierara arte, eta lerro anizkoitzen iruzkinak '{-' karaktere bikotearekin hasten dira, eta '-}'-ekin amaitzen dira.

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

```
Haskellek programazio alfabetatuzko metodo bat ere eskaintzen du iruzkintzeko, "txori-estiloa" izenekoa. Kasu horretan, '>'-rekin hasten diren lerro guztiak kode gisa interpretatzen dira; gainerakoak iruzkintzat hartzen dira. Beste baldintza bat da lerro bat beti zuri uztea kode-blokearen aurretik eta ondoren:

```
In Bird-style you have to leave a blank before the code.

> fact :: Integer -> Integer
> fact 0 = 1
> fact (n+1) = (n+1) \* fact n

And you have to leave a blank line after the code as well.

```
Programazio alfabetatua Haskell-en ere egin daiteke, LaTeX erabiliz. Kode-ingurunea Richard Bird-en estiloaren ordez erabil daiteke:
LaTeX estiloan hori aurreko adibidearen baliokidea da, kodearen ingurunea LaTeX-en hitzaurrean defini liteke. Hemen definizio sinple bat dago:

```
\usepackage{verbatim}
\newenvironment{code}{\verbatim}{\endverbatim}

```
geroago

```
% the LaTeX source file
The \verb|fact n| function call computes $n!$ if $n\ge 0$, here is a definition:\\
\begin{code}
fact :: Integer -> Integer
fact 0 = 1
fact (n+1) = (n+1) \* fact n
\end{code}
Here more explanation using \LaTeX{} markup

```

#### Java

Java kodearen zati honek `setToolTipText` metodoa deskribatzeko erabilitako bloke-iruzkin bat erakusten du. Formatua bat dator Sun Microsystems Javadoc-en estandarrekin. Javadoc prozesadoreak irakurria izateko diseinatuta dago iruzkina.

```
/\*\*
 \* This is a block comment in Java.
 \* The setToolTipText method registers the text to display in a tool tip.
 \* The text is displayed when the cursor lingers over the component.
 \*
 \* @param text The string to be displayed. If 'text' is null,
 \* the tool tip is turned off for this component.
 \*/
public void setToolTipText(String text) {
 // This is an inline comment in Java. TODO: Write code for this method.
}

```

#### Pascal

Niklaus Wirthen lengoaia-familian (Modula-2 eta Oberon barne), iruzkinak '(\*' karaktere-bikotearekin irekitzen dira eta '\*)' bikotearekin bukatu.

adibidez:

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

```
Pascalen dialekto modernoetan, aldiz, '{' eta '}' karaktereak erabiltzen dira.

#### Perl

Perl-ez eta scripting-eko beste lengoaia askotan lerroko iruzkinak hash ikurrarekin (#) hasten dira. 

```
# A simple example
# 
my $s = "Wikipedia"; # Sets the variable s to "Wikipedia".
print $s. "\n"; # Add a newline character after printing

```

#### R

R lengoaian hash karakterearekin (#) hasten diren lerroko iruzkinak bakarrik onartzen ditu.

```
# This is a comment
print("This is not a comment") # This is another comment

```

#### PHP

PHPko iruzkinak C++ estilokoak izan daitezke (linean nahiz blokean), edo hash-ak erabil daitezke. Javadoc-etik egokitutako estiloa da PHPDoc, eta PHP kodea dokumentatzeko estandar komuna da.

#### Python

Python lengoaian lerroko iruzkinek hash (#) karakterea erabiltzen dute, kode honen bi adibideetan bezala:

```
# This program prints "Hello World" to the screen
print("Hello World!")  # Note the new syntax

```
Artikulu honetan definitu den bezala, iruzkin multzokatuak ez daude teknikoki Python-en. *Komatxoak* karakterea hiru aldiz idatzita (""") erabil daiteke horretarako, baina interpreteak ez du enoratuko, "#" iruzkinetan bezala bezala. Hurrengo adibideetan, aipatutako karaktere hirukoitzak iruzkin gisa erabiltzen dira, baina docstrings gisa ere erabiltzen dira:

```
"""
Assuming this is file mymodule.py, then this string, being the
first statement in the file, will become the "mymodule" module's
docstring when the file is imported.
"""

class MyClass:
 """The class's docstring"""

    def my\_method(self):
 """The method's docstring"""

def my\_function():
 """The function's docstring"""

```

#### XML (edo HTML)

XML (edo HTML)-ko iruzkinak honela sartzen dira: 

```
<!--

```

eta zenbait lerrotan heda daitezke bukaerako karaktere hauetaraino: 

```
-->

```

Adibidez:

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

```

SGMLrekin bateragarria izateko, "--" (gidoi bikoitza) katea ez da onartzen iruzkinen barruan.

Segurtasun-arazoak
------------------

Interpretatutako lengoaiatan iruzkinak ikusgai daude programaren azken erabiltzailearentzat. Kasu batzuetan, hala nola "iruzkintzen" diren kode-sekzioetan, horrek segurtasun-zaurgarritasuna ekar dezake.

Erreferentziak
--------------

1. ↑   «Literate programming» *haskell.org*.
2. ↑   «Comments» *www.freepascal.org*.
3. 1 2    *Python 3 Basic Syntax.* .
4. ↑  "Python tip: You can use multi-line strings as multi-line comments", 11 September 2011, Guido van Rossum

Ikus, gainera
-------------

* Docstring, programa gauzatzen den bitartean banatu eta atxikitzen den iruzkin-mota espezifikoa.
* Shebang, #!-ren erabilera X motako sistemei buruzko script-etan interpreteen zuzendari gisa
* HTML iruzkin-etiketa
* Programazio alfabetatua, dokumentazio alternatiboaren paradigma
* Zenbait programazio-hizkuntzatan egindako iruzkinen sintaxia

Bibliografia
------------

* Movshovitz-Attias, Dana and Cohen, William W. (2013) Natural Language Models for Predicting Programming Comments. In Association for Computational Linguistics (ACL), 2013.

Kanpo estekak
-------------

* How to Write Comments Denis Krukovsky
* Source Code Documentation as a Live User Manual PTLogica
* How to Write Comments for the Javadoc Tool

|  |  |
| --- | --- |
| Autoritate kontrola | 
* **Wikimedia proiektuak**
* Wd Datuak: Q1141067

 |

* Wd Datuak: Q1141067