Comentário (programação de computador) - Comment (computer programming)

Uma ilustração do código-fonte Java com comentários do prólogo indicados em vermelho e comentários sequenciais em verde . O código do programa está em azul .

Na programação de computador , um comentário é uma explicação legível pelo programador ou anotação no código-fonte de um programa de computador . Eles são adicionados com o propósito de tornar o código-fonte mais fácil de ser entendido por humanos e geralmente são ignorados por compiladores e intérpretes . A sintaxe dos comentários em várias linguagens de programação varia consideravelmente.

Os comentários às vezes também são processados ​​de várias maneiras para gerar documentação externa ao próprio código-fonte por geradores de documentação ou usados ​​para integração com sistemas de gerenciamento de código-fonte e outros tipos de ferramentas de programação externas .

A flexibilidade fornecida pelos comentários permite um amplo grau de variabilidade, mas as convenções formais para seu uso costumam fazer parte dos guias de estilo de programação.

Visão geral

Os comentários são geralmente formatados como comentários de bloco (também chamados de comentários de prólogo ou comentários de fluxo ) ou comentários de linha (também chamados de comentários embutidos ).

Os comentários de bloco delimitam uma região do código-fonte que pode abranger várias linhas ou parte de uma única linha. Esta região é especificada com um delimitador inicial e um delimitador final . Algumas linguagens de programação (como MATLAB ) permitem que comentários em bloco sejam recursivamente aninhados uns dentro dos outros, mas outras (como Java ) não.

Os comentários de linha começam com um delimitador de comentário e continuam até o final da linha ou, em alguns casos, começam em uma coluna específica (deslocamento de linha de caractere) no código-fonte e continuam até o final da linha.

Algumas linguagens de programação empregam comentários de bloco e linha com delimitadores de comentário diferentes. Por exemplo, C ++ possui comentários de bloco delimitados por /*e */que podem abranger várias linhas e comentários de linha delimitados por //. Outros idiomas suportam apenas um tipo de comentário. Por exemplo, os comentários Ada são comentários de linha: eles começam com --e continuam até o final da linha.

Usos

A melhor forma de usar os comentários está sujeita a disputa; comentadores diferentes ofereceram pontos de vista variados e às vezes opostos. Existem muitas maneiras diferentes de escrever comentários e muitos comentaristas oferecem conselhos conflitantes.

Planejamento e revisão

Os comentários podem ser usados ​​como uma forma de pseudocódigo para delinear a intenção antes de escrever o código real. Nesse caso, ele deve explicar a lógica por trás do código, e não o próprio código. .

/* 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]);
}

Se este tipo de comentário for deixado, ele simplifica o processo de revisão, permitindo uma comparação direta do código com os resultados pretendidos. Uma falácia lógica comum é que o código fácil de entender faz o que deve fazer.

Descrição do código

Os comentários podem ser usados ​​para resumir o código ou para explicar a intenção do programador. De acordo com essa escola de pensamento, reformular o código em inglês simples é considerado supérfluo; a necessidade de reexplicar o código pode ser um sinal de que ele é muito complexo e deve ser reescrito ou que a nomenclatura está incorreta.

"Não documente código inválido - reescreva-o."
"Bons comentários não repetem o código nem o explicam. Eles esclarecem sua intenção. Os comentários devem explicar, em um nível mais alto de abstração do que o código, o que você está tentando fazer."

Os comentários também podem ser usados ​​para explicar por que um bloco de código não parece se adequar às convenções ou práticas recomendadas. Isso é especialmente verdadeiro para projetos que envolvem muito pouco tempo de desenvolvimento ou na correção de bugs. Por exemplo:

' 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")

Descrição do algoritmo

Às vezes, o código-fonte contém uma solução nova ou notável para um problema específico. Nesses casos, os comentários podem conter uma explicação da metodologia. Essas explicações podem incluir diagramas e provas matemáticas formais. Isso pode constituir uma explicação do código, em vez de um esclarecimento de sua intenção; mas outras pessoas encarregadas de manter a base do código podem achar essa explicação crucial. Isso pode ser especialmente verdadeiro no caso de domínios de problemas altamente especializados; ou otimizações, construções ou chamadas de função raramente usadas.

Por exemplo, um programador pode adicionar um comentário para explicar por que um tipo de inserção foi escolhido em vez de um quicksort , já que o primeiro é, em teoria, mais lento do que o último. Isso pode ser escrito da seguinte forma:

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

Inclusão de recursos

Logotipos , diagramas e fluxogramas que consistem em construções de arte ASCII podem ser inseridos no código-fonte formatado como um comentário. Além disso, avisos de direitos autorais podem ser incorporados ao código-fonte como comentários. Os dados binários também podem ser codificados em comentários por meio de um processo conhecido como codificação binário para texto , embora essa prática seja incomum e normalmente relegada a arquivos de recursos externos.

O fragmento de código a seguir é um diagrama ASCII simples que descreve o fluxo do processo para um script de administração do sistema contido em um arquivo de script do Windows em execução no Windows Script Host . Embora uma seção marcando o código apareça como um comentário, o diagrama em si na verdade aparece em uma seção XML CDATA , que é tecnicamente considerada distinta dos comentários, mas pode servir a propósitos semelhantes.

<!-- 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)  
]]>
</resource>

Embora esse diagrama idêntico pudesse facilmente ter sido incluído como um comentário, o exemplo ilustra uma instância em que um programador pode optar por não usar comentários como forma de incluir recursos no código-fonte.

Metadados

Os comentários em um programa de computador geralmente armazenam metadados sobre um arquivo de programa.

Em particular, muitos mantenedores de software colocam diretrizes de envio em comentários para ajudar as pessoas que lêem o código-fonte daquele programa a enviar quaisquer melhorias que façam de volta ao mantenedor.

Outros metadados incluem: o nome do criador da versão original do arquivo do programa e a data em que a primeira versão foi criada, o nome do atual mantenedor do programa, os nomes de outras pessoas que editaram o arquivo do programa até agora , o URL da documentação sobre como usar o programa, o nome da licença do software para este arquivo de programa, etc.

Quando um algoritmo em alguma seção do programa é baseado em uma descrição em um livro ou outra referência, os comentários podem ser usados ​​para fornecer o número da página e o título do livro ou Solicitação de Comentários ou outra referência.

Depurando

Uma prática comum do desenvolvedor é comentar um trecho de código, o que significa adicionar sintaxe de comentário fazendo com que esse bloco de código se torne um comentário, de modo que não seja executado no programa final. Isso pode ser feito para excluir certas partes do código do programa final ou (mais comumente) pode ser usado para encontrar a origem de um erro. Comentando sistematicamente e executando partes do programa, a origem de um erro pode ser determinada, permitindo que seja corrigido.

Um exemplo de código de comentário para fins de exclusão está abaixo:

O fragmento de código acima sugere que o programador optou por desativar a opção de depuração por algum motivo.

Muitos IDEs permitem adicionar ou remover rapidamente esses comentários com opções de menu simples ou combinações de teclas. O programador precisa apenas marcar a parte do texto que deseja (des) comentar e escolher a opção apropriada.

Geração automática de documentação

As ferramentas de programação às vezes armazenam documentação e metadados em comentários. Isso pode incluir posições de inserção para inclusão automática de arquivo de cabeçalho, comandos para definir o modo de realce de sintaxe do arquivo ou o número de revisão do arquivo . Esses comentários de controle funcional também são comumente chamados de anotações . Manter a documentação dentro dos comentários do código fonte é considerada uma forma de simplificar o processo de documentação, bem como aumentar as chances de que a documentação seja mantida atualizada com as alterações no código.

Exemplos de geradores de documentação incluem os programas Javadoc para uso com Java , Ddoc para D , Doxygen para C , C ++ , Java, IDL , Visual Expert para PL / SQL , Transact-SQL , PowerBuilder e PHPDoc para PHP . Formas de docstring são suportadas por Python , Lisp , Elixir e Clojure .

C # , F # e Visual Basic .NET implementam um recurso semelhante chamado "Comentários XML" que são lidos pelo IntelliSense a partir do assembly .NET compilado .

Extensão de sintaxe

Ocasionalmente, elementos de sintaxe que originalmente deveriam ser comentários são reaproveitados para transmitir informações adicionais a um programa, como " comentários condicionais ". Esses "comentários quentes" podem ser a única solução prática que mantém a compatibilidade com versões anteriores, mas são amplamente considerados como um erro .

Usos diretivos

Há casos em que os caracteres de comentário normais são cooptados para criar uma diretiva especial para um editor ou intérprete.

Dois exemplos disso direcionando um intérprete são:

  • O Unix " shebang " - #!- usado na primeira linha de um script para apontar para o interpretador a ser usado.
  • "Comentários mágicos" que identificam a codificação que um arquivo de origem está usando, por exemplo, PEP 263 do Python.

O script abaixo para um sistema semelhante ao Unix mostra esses dois usos:

#!/usr/bin/env python3
# -*- coding: UTF-8 -*-
print("Testing")

Um pouco semelhante é o uso de comentários em C para comunicar a um compilador que uma "queda" padrão em uma instrução case foi feita deliberadamente:

switch (command) {
    case CMD_SHOW_HELP_AND_EXIT:
      do_show_help();
      /* Fall thru */
    case CMD_EXIT:
      do_exit();
      break;
    case CMD_OTHER:
      do_other();
      break;
    /* ... etc. ... */
  }

Inserir tal /* Fall thru */comentário para leitores humanos já era uma convenção comum, mas em 2017 o compilador gcc começou a procurar por eles (ou outras indicações de intenção deliberada) e, se não for encontrado, emitindo: "aviso: esta declaração pode falhar" .

Muitos editores e IDEs lerão comentários especialmente formatados. Por exemplo, o recurso "modeline" do Vim ; o que mudaria o manuseio das guias ao editar uma fonte com este comentário incluído próximo ao topo do arquivo:

# vim: tabstop=8 expandtab shiftwidth=4 softtabstop=4

Alívio de estresse

Às vezes, os programadores adicionam comentários como uma forma de aliviar o estresse, comentando sobre ferramentas de desenvolvimento, concorrentes, empregadores, condições de trabalho ou a qualidade do próprio código. A ocorrência desse fenômeno pode ser facilmente observada em recursos online que rastreiam palavrões no código-fonte.

Vistas normativas

Existem várias visões normativas e opiniões de longa data sobre o uso adequado de comentários no código-fonte. Alguns deles são informais e baseados em preferências pessoais, enquanto outros são publicados ou promulgados como diretrizes formais para uma comunidade específica.

Necessidade de comentários

Os especialistas têm pontos de vista variados sobre se e quando os comentários são apropriados no código-fonte. Alguns afirmam que o código-fonte deve ser escrito com poucos comentários, na base de que o código-fonte deve ser autoexplicativo ou autodocumentado . Outros sugerem que o código deve ser amplamente comentado (não é incomum que mais de 50% dos caracteres que não sejam de espaço em branco no código-fonte estejam contidos nos comentários).

Entre essas visões está a afirmação de que os comentários não são benéficos nem prejudiciais por si próprios, e o que importa é que eles sejam corretos e mantidos em sincronia com o código-fonte e omitidos se forem supérfluos, excessivos, difíceis de manter ou inúteis.

Os comentários às vezes são usados ​​para documentar contratos na abordagem de projeto por contrato para a programação.

Nível de detalhe

Dependendo do público-alvo do código e de outras considerações, o nível de detalhe e a descrição podem variar consideravelmente.

Por exemplo, o seguinte comentário Java seria adequado em um texto introdutório projetado para ensinar programação inicial:

String s = "Wikipedia"; /* Assigns the value "Wikipedia" to the variable s. */

Esse nível de detalhe, entretanto, não seria apropriado no contexto do código de produção ou em outras situações que envolvam desenvolvedores experientes. Essas descrições rudimentares são inconsistentes com a diretriz: "Bons comentários ... esclarecem a intenção." Além disso, para ambientes de codificação profissional, o nível de detalhe é normalmente bem definido para atender a um requisito de desempenho específico definido pelas operações de negócios.

Estilos

Existem muitas alternativas estilísticas disponíveis ao considerar como os comentários devem aparecer no código-fonte. Para projetos maiores envolvendo uma equipe de desenvolvedores, os estilos de comentário são acordados antes do início do projeto ou evoluem por uma questão de convenção ou necessidade conforme o projeto cresce. Normalmente, os programadores preferem estilos consistentes, não obstrutivos, fáceis de modificar e difíceis de quebrar.

Bloquear comentário

Os fragmentos de código a seguir em C demonstram apenas um pequeno exemplo de como os comentários podem variar estilisticamente, embora ainda transmitam as mesmas informações básicas:

/*
     This is the comment body.
     Variation One.
*/
/***************************\
*                           *
* This is the comment body. *
* Variation Two.            *
*                           *
\***************************/

Fatores como preferência pessoal, flexibilidade das ferramentas de programação e outras considerações tendem a influenciar as variantes estilísticas usadas no código-fonte. Por exemplo, a variação dois pode ser desfavorecida entre os programadores que não têm editores de código-fonte que podem automatizar o alinhamento e a aparência visual do texto nos comentários.

O consultor de software e comentarista de tecnologia Allen Holub é um especialista que defende o alinhamento das margens esquerdas dos comentários:

 /* This is the style recommended by Holub for C and C++.
  * It is demonstrated in ''Enough Rope'', in rule 29.
  */
 /* This is another way to do it, also in C.
 ** It is easier to do in editors that do not automatically indent the second
 ** through last lines of the comment one space from the first.
 ** It is also used in Holub's book, in rule 31.
 */

O uso de / * e * / como delimitadores de comentário de bloco foi herdado de PL / I para a linguagem de programação B, o predecessor imediato da linguagem de programação C.

Comentários de linha

Os comentários de linha geralmente usam um delimitador arbitrário ou sequência de tokens para indicar o início de um comentário e um caractere de nova linha para indicar o final de um comentário.

Neste exemplo, todo o texto dos caracteres ASCII // até o final da linha é ignorado.

// -------------------------
// This is the comment body.
// -------------------------

Freqüentemente, esse comentário deve começar na extrema esquerda e se estender a toda a linha. No entanto, em muitos idiomas, também é possível colocar um comentário inline com uma linha de comando, para adicionar um comentário a ele - como neste exemplo de Perl:

print $s . "\n";     # Add a newline character after printing

Se uma linguagem permite comentários de linha e comentários de bloco, as equipes de programação podem decidir sobre uma convenção de usá-los de forma diferente: por exemplo, comentários de linha apenas para comentários menores e comentários de bloco para descrever abstrações de nível superior.

Tag

Os programadores podem usar tags informais nos comentários para ajudar na indexação de problemas comuns. Eles podem ser pesquisados ​​com ferramentas de programação comuns, como o utilitário grep do Unix ou até mesmo com destaque de sintaxe em editores de texto . Às vezes, eles são chamados de "codetags" ou "tokens".

Essas tags variam amplamente, mas podem incluir:

  • BUG - um bug conhecido que deve ser corrigido.
  • FIXME - deve ser corrigido.
  • HACK - uma solução alternativa.
  • TODO - algo a ser feito.
  • UNDONE - uma reversão ou "reversão" do código anterior.
  • XXX - avisa outros programadores sobre códigos problemáticos ou equivocados

Exemplos

Comparação

As convenções tipográficas para especificar comentários variam amplamente. Além disso, as linguagens de programação individuais às vezes fornecem variantes exclusivas. Para uma revisão detalhada, consulte o artigo de comparação de linguagem de programação .

Ada

A linguagem de programação Ada usa '-' para indicar um comentário até o final da linha.

Por exemplo:

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

APL

O APL usa para indicar um comentário até o final da linha.

Por exemplo:

⍝ Now add the numbers:
ca+b ⍝ addition

Em dialetos que têm as primitivas ("esquerda") e ("direita"), os comentários podem frequentemente estar dentro ou em instruções separadas, na forma de strings ignoradas:

d2×c 'where' ca+ 'bound' b

AppleScript

Esta seção do código AppleScript mostra os dois estilos de comentários usados ​​nessa linguagem.

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

-- Show the greeting
greet("Hello")

BASIC

Neste fragmento de código BASIC clássico, a palavra-chave REM ( "Remark" ) é usada para adicionar comentários.

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

Em Microsoft BASICs posteriores , incluindo Quick Basic , Q Basic , Visual Basic , Visual Basic .NET e VB Script ; e em descendentes como FreeBASIC e Gambas, qualquer texto em uma linha após um caractere '(apóstrofo) também é tratado como um comentário.

Um exemplo em Visual Basic .NET:

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

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

C

Este fragmento de código C demonstra o uso de um comentário de prólogo ou "comentário de bloco" para descrever o propósito de uma instrução condicional . O comentário explica os principais termos e conceitos e inclui uma pequena assinatura do programador que criou o código.

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

Desde C99, também foi possível usar a sintaxe // do C ++, indicando um comentário de uma única linha.

Configuração Cisco IOS e IOS-XE

O ponto de exclamação ( ! ) Pode ser usado para marcar comentários no modo de configuração de um roteador Cisco, no entanto, tais comentários não são salvos na memória não volátil (que contém a configuração de inicialização), nem são exibidos pelo comando "show run" .

É possível inserir conteúdo legível por humanos que realmente faz parte da configuração e pode ser salvo na configuração de inicialização da NVRAM via:

  • O comando "descrição", usado para adicionar uma descrição à configuração de uma interface ou de um vizinho BGP
  • O parâmetro "nome", para adicionar uma observação a uma rota estática
  • O comando "observação" nas listas de acesso
! Paste the text below to reroute traffic manually
config t
int gi0/2
no shut
ip route 0.0.0.0 0.0.0.0 gi0/2 name ISP2
no ip route 0.0.0.0 0.0.0.0 gi0/1 name ISP1
int gi0/1
shut
exit

Fusão a frio

ColdFusion usa comentários semelhantes aos comentários de HTML , mas em vez de dois travessões, ele usa três. Esses comentários são capturados pelo mecanismo ColdFusion e não impressos no navegador.

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

Fortran IV

Este fragmento de código Fortran IV demonstra como os comentários são usados ​​nessa linguagem, que é muito orientada a colunas. Uma letra "C" na coluna 1 faz com que toda a linha seja tratada como um comentário.

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

Observe que as colunas de uma linha são tratadas como quatro campos: 1 a 5 é o campo do rótulo, 6 faz com que a linha seja considerada uma continuação da instrução anterior; e as declarações e declarações vão de 7 a 72.

Fortran 90

Este fragmento de código Fortran demonstra como os comentários são usados ​​nessa linguagem, com os próprios comentários descrevendo as regras básicas de formatação.

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

Os comentários de linha em Haskell começam com '-' (dois hifens) até o final da linha, e os comentários de várias linhas começam com '{-' e terminam com '-}'.

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

Haskell também fornece um método de programação literário de comentários conhecido como "Estilo de pássaro". Neste, todas as linhas que começam com> são interpretadas como código, todo o resto é considerado um comentário. Um requisito adicional é que você sempre deixe uma linha em branco antes e depois do bloco de código:

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.

A programação literária também pode ser feita em Haskell, usando LaTeX . O ambiente de código pode ser usado no lugar do estilo de Richard Bird: No estilo LaTeX , isso é equivalente ao exemplo acima, o ambiente de código pode ser definido no preâmbulo LaTeX. Aqui está uma definição simples:

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

mais tarde em

% 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

Este fragmento de código Java mostra um comentário de bloco usado para descrever o setToolTipTextmétodo. A formatação é consistente com os padrões Javadoc da Sun Microsystems . O comentário foi projetado para ser lido pelo processador Javadoc.

/**
 * 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.
}

JavaScript

JavaScript usa // para preceder comentários e / * * / para comentários de várias linhas.

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

Lua

A linguagem de programação Lua usa hífens duplos,, --para comentários de linha única de maneira semelhante às linguagens Ada , Eiffel , Haskell , SQL e VHDL . Lua também tem comentários em bloco, que começam com --[[e são executados até um fechamento]]

Por exemplo:

--[[A multi-line
long comment
]]
print(20)   -- print the result

Uma técnica comum para comentar um trecho de código é colocar o código entre --[[e --]], como abaixo:

--[[
print(10)
--]]
-- no action (commented out)

Nesse caso, é possível reativar o código adicionando um único hífen à primeira linha:

---[[
print(10)
--]]
--> 10

No primeiro exemplo, o --[[na primeira linha inicia um comentário longo e os dois hifens na última linha ainda estão dentro desse comentário. No segundo exemplo, a sequência ---[[inicia um comentário comum de uma linha, de forma que a primeira e a última linhas se tornem comentários independentes. Nesse caso, printestá fora dos comentários. Nesse caso, a última linha se torna um comentário independente, pois começa com --.

Comentários longos em Lua podem ser mais complexos do que esses, como você pode ler na seção chamada "Strings longas" cf Programação em Lua .

MATLAB

Na linguagem de programação do MATLAB , o caractere '%' indica um comentário de uma única linha. Comentários de várias linhas também estão disponíveis por meio de colchetes% {e%} e podem ser aninhados, por exemplo

% 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)

Nim

Nim usa o caractere '#' para comentários embutidos. Os comentários do bloco de várias linhas são abertos com '# [' e fechados com '] #'. Os comentários do bloco de várias linhas podem ser aninhados.

Nim também tem comentários de documentação que usam marcações Markdown e ReStructuredText mistas . Os comentários da documentação inline usam '##' e os comentários da documentação do bloco de várias linhas são abertos com '## [' e fechados com '] ##'. O compilador pode gerar documentação HTML , LaTeX e JSON a partir dos comentários da documentação. Os comentários da documentação fazem parte da árvore de sintaxe abstrata e podem ser extraídos usando macros.

## Documentation of the module *ReSTructuredText* and **MarkDown**
# This is a comment, but it is not a documentation comment.

type Kitten = object  ## Documentation of type
  age: int  ## Documentation of field

proc purr(self: Kitten) =
  ## Documentation of function
  echo "Purr Purr"  # This is a comment, but it is not a documentation comment.

# This is a comment, but it is not a documentation comment.

OCaml

OCaml usa comentários aninhados, o que é útil ao comentar um bloco de código.

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

Pascal

Na família de idiomas pascal de Niklaus Wirth (incluindo Modula-2 e Oberon ), os comentários são abertos com '(*' e completados com '*)'.

por exemplo:

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

Em dialetos modernos de Pascal, '{' e '}' são usados ​​no lugar.

Perl

Comentários de linha em Perl e em muitas outras linguagens de script começam com um símbolo hash (#).

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

Em vez de uma construção de bloco de comentários regular, Perl usa Plain Old Documentation , uma linguagem de marcação para programação literária , por exemplo:

=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;
}

R

R suporta apenas comentários embutidos iniciados pelo caractere hash (#).

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

Raku

Raku (anteriormente chamado de Perl 6) usa os mesmos comentários de linha e comentários de documentação POD que o Perl normal (consulte a seção Perl acima), mas adiciona um tipo de comentário de bloco configurável: "comentários de várias linhas / incorporados".

Eles começam com um caractere hash, seguido por um crase e, em seguida, alguns caracteres de colchetes de abertura e terminam com o caractere de colchetes de fechamento correspondente. O conteúdo não pode apenas abranger várias linhas, mas também pode ser incorporado inline.

#`{{ "commenting out" this version 
toggle-case(Str:D $s)

Toggles the case of each character in a string:

  my Str $toggled-string = toggle-case("mY NAME IS mICHAEL!");

}}

sub toggle-case(Str:D $s) #`( this version of parens is used now ){
    ...
}

PHP

Os comentários em PHP podem ser no estilo C ++ (inline e em bloco) ou usar hashes. PHPDoc é um estilo adaptado de Javadoc e é um padrão comum para documentar código PHP.

PowerShell

Comentários no Windows PowerShell

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

<# Multi
   Line
   Comment #>

Write-Host "Goodbye, world!"

Pitão

Os comentários in-line em Python usam o caractere hash (#), como nos dois exemplos neste código:

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

Os comentários de bloqueio, conforme definido neste artigo, não existem tecnicamente no Python. Uma string literal representada por uma string entre aspas triplas pode ser usada, mas não é ignorada pelo interpretador da mesma forma que o comentário "#". Nos exemplos abaixo, as strings triplas entre aspas agem dessa forma como comentários, mas também são tratadas como docstrings :

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

Rubi

Comentários em Ruby .

Comentário de linha única: (a linha começa com hash "#")

puts "This is not a comment"

# this is a comment

puts "This is not a comment"

Comentário multilinha: (os comentários vão entre as palavras-chave "início" e "fim")

puts "This is not a comment"

=begin

whatever goes in these lines

is just for the human reader

=end

puts "This is not a comment"

SQL

Os comentários padrão em SQL são em formato de apenas uma linha, usando dois travessões:

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

Como alternativa, uma sintaxe de formato de comentário idêntica ao estilo de "comentário de bloco" usado na sintaxe para C e Java é compatível com Transact-SQL , MySQL , SQLite , PostgreSQL e Oracle .

O MySQL também suporta comentários do caractere hash (#) até o final da linha.

Rápido

Comentários de linha única começam com duas barras (//):

// This is a comment.

Os comentários de várias linhas começam com uma barra seguida por um asterisco (/ *) e terminam com um asterisco seguido por uma barra (* /):

/* This is also a comment
 but is written over multiple lines. */

Os comentários de várias linhas no Swift podem ser aninhados dentro de outros comentários de várias linhas. Você escreve comentários aninhados iniciando um bloco de comentário de várias linhas e, em seguida, iniciando um segundo comentário de várias linhas dentro do primeiro bloco. O segundo bloco é então fechado, seguido pelo primeiro bloco:

/* This is the start of the first multiline comment.
 /* This is the second, nested multiline comment. */
 This is the end of the first multiline comment. */

XML (ou HTML)

Comentários em XML (ou HTML) são introduzidos com

<!--

e pode se espalhar por várias linhas até o terminador,

-->

Por exemplo,

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

Para compatibilidade com SGML , a string "-" (hífen duplo) não é permitida nos comentários.

Problemas de segurança

Em idiomas interpretados, os comentários podem ser visualizados pelo usuário final do programa. Em alguns casos, como seções de código "comentadas", isso pode representar uma vulnerabilidade de segurança .

Veja também

Notas e referências

Leitura adicional

links externos