Ohar (programazioa)

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.

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

• Datuak: Q1141067