Comentário (programação de computador)

Da Wikipédia, a enciclopédia livre
Ir para navegação Pular para pesquisar
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 . [1] [2] 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 ). [3]

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. [4] [5] [6]

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. [6]

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. [6]

Usos

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

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 backward por todos os elementos retornados pelo servidor 
(eles devem ser processados ​​cronologicamente) * / 
for  ( i  =  ( numElementsReturned  -  1 );  i  > =  0 ;  i - )  { 
    / * processar os dados de cada elemento * / 
    updatePattern ( i ,  ReturnElements [ 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." [9]
"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." [10]

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:

'A segunda variável escurece devido a erros de servidor produzidos ao reutilizar os dados do formulário. Não há 
documentação disponível sobre o problema de comportamento do servidor, então apenas codifique em torno dele. 
vtx  =  servidor . mappath ( "configurações locais" )

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. [11]

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:

 lista  =  [ f  ( b ),  f  ( b ),  f  ( c ),  f  ( d ),  f  ( a ),  ... ] ; 
 // Precisa de uma classificação estável. Além disso, o desempenho realmente não importa. 
 inserção_sort  ( lista );

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. [12] 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. [13]

<! - 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. [13]

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.

Depuração

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 de documentação automática

As ferramentas de programação às vezes armazenam documentação e metadados em comentários. [14] Estes podem 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 , [15] ou o número de revisão do arquivo . [16] 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. [17]

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 . [18]

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 . [19]

Extensão 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 . [20]

A diretriz usa

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, [21] por exemplo, PEP 263 do Python. [22]

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

#! / usr / bin / env python3 
# - * - codificação: UTF-8 - * - 
print ( "Teste" )

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  ( comando )  { 
    case  CMD_SHOW_HELP_AND_EXIT : 
      do_show_help (); 
      / * Fall thru * / 
    case  CMD_EXIT : 
      do_exit (); 
      pausa ; 
    case  CMD_OTHER : 
      do_other (); 
      pausa ; 
    / * ... 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" . [23]

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 do 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. [24] A ocorrência desse fenômeno pode ser facilmente vista em recursos online que rastreiam palavrões no código-fonte. [25]

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. [26] [27] 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. [28]

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. [9] [29] Alguns afirmam que o código-fonte deve ser escrito com poucos comentários, com base em que o código-fonte deve ser autoexplicativo ou autodocumentado . [9] Outros sugerem que o código deve ser amplamente comentado (não é incomum que mais de 50% dos caracteres que não sejam espaços em branco no código-fonte estejam contidos nos comentários). [30] [31]

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. [32] [33]

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" ;  / * Atribui o valor "Wikipedia" à variável s. * /

Esse nível de detalhe, no entanto, 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." [10] 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. [31]

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. [34]

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:

/ * 
     Este é o corpo do comentário. 
     Variação um. 
* /
/ **************************** \ 
* * 
* Este é o corpo do comentário. * 
* Variação Dois. * 
* * 
\ **************************** /

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 [35] é um especialista que defende o alinhamento das bordas esquerdas dos comentários: [36]

 / * Este é o estilo recomendado por Holub para C e C ++. 
  * É demonstrado em '' Corda Suficiente '', na regra 29. 
  * /
 / * Esta é outra maneira de fazer isso, também em C. 
** É mais fácil de fazer em editores que não recuam automaticamente a segunda 
** até a última linha do comentário um espaço da primeira. 
** Também é usado no livro de Holub, na regra 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. [37]

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.

// ------------------------- 
// Este é o corpo do comentário. 
// -------------------------

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:

imprimir  $ s  .  "\ n" ;      # Adicione um caractere de nova linha após a impressão

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.

Tags

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

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:

  - a tarefa do controlador de tráfego aéreo recebe solicitações para o 
   tipo de tarefa de  decolagem e pouso Controlador ( My_Runway : Runway_Access ) é - entradas de tarefa para a entrada de passagem de mensagem síncrona Request_Takeoff ( ID : em Airplane_ID ; Decolagem : out Runway_Access ); entrada Request_Approach ( ID : em Airplane_ID ; Approach : fora de Runway_Access ); controlador final ;   
      
           
          
    

APL

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

Por exemplo:

⍝ Agora adicione os números: 
c a + b  ⍝ adição

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

d 2 × c  'onde'  c a +  'limite'  b

AppleScript

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

(* 
Este programa exibe uma saudação. 
*) 
Na  greet ( MyGreeting ) 
     de diálogo exibição  MyGreeting  &  "mundo!" 
fim  cumprimentar

- Mostrar a saudação 
greet ( "Olá" )

BASIC

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

10 REM Este programa BASIC mostra o uso das instruções PRINT e GOTO. 15 REM Preenche a tela com a frase "OLÁ" 20 IMPRIME "OLÁ" 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 )  Manipula o  Button1 . Clique em 
        'O código a seguir é executado quando o usuário 
        ' clica no botão na janela do programa. 
        comentários rem ainda existem.

        MessageBox . Show ( "Hello, World" )  'Mostra uma janela pop-up com uma saudação 
    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.

 / * 
  * Verifique se ultrapassamos nosso limite máximo de processo, mas certifique-se de 
  * excluir o root. Isso é necessário para permitir que o login e 
  * amigos definam o limite do processo por usuário para algo menor 
  * do que a quantidade de processos em execução pelo root. - Rik 
  * / 
 if  ( atomic_read ( & p -> usuário -> processos )  > =  p -> rlim [ RLIMIT_NPROC ]. Rlim_cur 
     &&  ! Capaz ( CAP_SYS_ADMIN )  &&  ! Capaz ( 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.

Cisco IOS e configuração 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" . [41] [42]

É 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
! Cole o texto abaixo para redirecionar o tráfego manualmente
config t
int gi0 / 2
não feche
ip route 0.0.0.0 0.0.0.0 gi0 / 2 nome ISP2
sem rota ip 0.0.0.0 0.0.0.0 gi0 / 1 nome ISP1
int gi0 / 1
fechar
saída

ColdFusion

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.

 <! --- Isso imprime "Hello World" no navegador. ---> 
 <cfoutput> 
   Olá Mundo < 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 As linhas que começam com 'C' (na primeira coluna ou 'comentário') são comentários 
C 
ESCREVER ( 6 , 610 )   610 FORMATO ( 12 H OLÁ MUNDO ) FIM       
   
      

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

! * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * 
! * Todos os caracteres após um ponto de exclamação são considerados comentários * 
! * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * 
Programa comment_test 
    imprimir  '(A)' ,  'Olá, mundo'  ! O Fortran 90 introduziu a opção de comentários embutidos. 
fim do programa

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 '-}'.

{- este é um comentário 
em mais linhas -} 
- e este é um comentário em uma linha 
putStrLn  "Wikipedia"   - este é outro comentário

Haskell também fornece um método de programação literário de comentários conhecido como "Estilo de pássaro". [43] Neste, todas as linhas começando 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:

No estilo Bird, você deve deixar um espaço em branco antes do código.

> fato  ::  Inteiro  ->  Inteiro 
> fato  0  =  1 
> fato  ( n + 1 )  =  ( n + 1 )  *  fato  n

E você também deve deixar uma linha em branco após o código.

A programação literária também pode ser feita em Haskell, usando LaTeX . O ambiente de código pode ser usado em vez 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

% o arquivo de origem LaTeX 
O \ verb | fact n | chamada de função calcula $ n ! $ if $ n \ ge 0 $ , aqui está uma definição: \\ \ begin { code } fact :: Integer -> Inteiro fato 0 = 1 fato ( n + 1 ) = ( n + 1 ) * fato n \ end { code } 
Aqui, mais explicações usando 

    
   
      
Marcação
 \ LaTeX {}

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.

/ ** 
* Este é um comentário de bloco em Java. 
* O método setToolTipText registra o texto a ser exibido em uma dica de ferramenta. 
* O texto é exibido quando o cursor passa sobre o componente. 
* 
* @param text A string a ser exibida. Se 'texto' for nulo, 
* a dica de ferramenta será desativada para este componente. 
* / 
public  void  setToolTipText ( String  text )  { 
    // Este é um comentário embutido em Java. TODO: Escreva o código para este método. 
}

JavaScript

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

// Um ​​comentário de JavaScript de linha única 
var  iNum  =  100 ; 
var  iTwo  =  2 ;  // Um ​​comentário no final da linha 
/ * 
comentário JavaScript de várias linhas 
* /

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:

- [[Um 
comentário longo de 
várias linhas ]] 
imprimir ( 20 )    - imprimir o resultado

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

- [[ 
imprimir (10) 
-]] 
- nenhuma ação (comentado)

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

--- [[ 
imprimir ( 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

% Estes são os derivados para cada termo
d = [ 0 - 1 0 ];    

% { 
  % { 
    (Exemplo de um comentário aninhado, recuo é para cosméticos (e ignorado).) 
  %}
  Nós formar a sequência , seguindo o Taylor fórmula .       
  Nota que nós ' re operacional em um vector .      
%}
seq = d . * ( x - c ) . ^ n ./ ( fatorial ( n ))       

% Nós somamos para obter a aproximação de Taylor
aprox = soma ( 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. [45]

## Documentação do módulo * ReSTructuredText * e ** MarkDown ** 
# Este é um comentário, mas não é um comentário de documentação.

tipo  Kitten  =  objeto   ## Documentação do tipo 
  idade :  int   ## Documentação do campo

proc purr ( self :  Kitten )  = 
  ## Documentação da função 
  echo  "Purr Purr"   # Este é um comentário, mas não é um comentário de documentação.

# Este é um comentário, mas não é um comentário de documentação.

OCaml

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

codeLine (* nível de comentário 1 (* nível de comentário 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:

(* diagonais de teste *) 
columnDifference  : =  testColumn  -  coluna ; 
if  ( row  +  columnDifference  =  testRow )  ou 
    .......

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

Perl

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

# Um exemplo simples 
# 
my  $ s  =  "Wikipedia" ;  # Define a variável s para "Wikipedia". 
imprimir  $ s  .  "\ n" ;      # Adicione um caractere de nova linha após a impressão

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 , [47] por exemplo: [48]

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

Crie um novo objeto de lista. As propriedades podem ser especificadas por meio de uma 
referência de hash como esta:

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

Consulte os métodos / propriedades individuais para obter detalhes.

= corte

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

R

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

# Este é um comentário 
imprimir ( "Isto não é um comentário" )   # Este é outro comentário

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". [49]

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. [49] O conteúdo não pode apenas abranger várias linhas, mas também pode ser incorporado inline.

# `{{" comentando "esta versão 
alternar entre maiúsculas e minúsculas (Str: D $ s)

Alterna o caso de cada caractere em uma string:

  meu Str $ toggled-string = toggle-case ("MEU NOME É MICHAEL!");

}}

sub  toggle-case ( Str: D  $ s ) # `(esta versão dos parênteses é usada agora) {
    ...
}

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

# Comentário de uma linha 
Write-Host  "Hello, World!"

<# 
   Comentário de várias    linhas 
#>

Write-Host  "Adeus, mundo!"

Python

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

# Este programa imprime "Hello World" na tela de 
impressão ( "Hello World!" )   # Observe a nova sintaxe

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

"" " 
Supondo que este seja o arquivo mymodule.py, então esta string, sendo a 
primeira instrução no arquivo, se tornará a 
docstring 
do módulo" mymodule " quando o arquivo for importado. " ""

class  MyClass : 
    "" "A docstring da classe" ""

    def  my_method ( self ): 
        "" "A docstring do método" ""

def  my_function (): 
    "" "A docstring da função" ""

Ruby

Comentários em Ruby .

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

coloca  "Isto não é um comentário"

# isto é um comentário

coloca  "Isto não é um comentário"

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

coloca  "Isto não é um comentário"

= começar

o que quer que seja nestas linhas

é apenas para o leitor humano

= fim

coloca  "Isto não é um comentário"

SQL

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

- Este é um comentário de uma única linha 
- seguido por uma segunda linha 
SELECT  COUNT ( * ) 
       FROM  Authors 
       WHERE  Authors . nome  =  'Smith' ;  - Nota: queremos apenas 'smith' 
                                     - este comentário aparece após o código SQL

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 . [52] [53] [54] [55] [56]

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

Swift

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

// Este é um comentário.

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 (* /):

/ * Este também é um comentário, 
mas é escrito em várias linhas. * /

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:

/ * Este é o início do primeiro comentário multilinha. 
/ * Este é o segundo comentário de várias linhas aninhado. * / 
Este é o final do primeiro comentário multilinha. * /

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,

<! - selecione o contexto aqui -> 
<param  name = "context"  value = "public"  />

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

As questões 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 . [57]

Veja também

Notas e referências

  1. ^ O código-fonte pode ser dividido em código de programa (que consiste em instruções traduzíveis por máquina); e comentários (que incluem notas legíveis por humanos e outros tipos de anotações em apoio ao código do programa). Penny Grubb, Armstrong Takang (2003). Manutenção de software: conceitos e prática . World Scientific. pp. 7, plese start120-121. ISBN 978-981-238-426-3.
  2. ^ Para os fins deste artigo, os comentários da linguagem de programação são tratados como indistintos dos comentários que aparecem em linguagens de marcação , arquivos de configuração e outros contextos semelhantes. Além disso, a linguagem de marcação é frequentemente integrada ao código da linguagem de programação, especialmente no contexto de geração de código . Veja, por exemplo, Ganguli, Madhushree (2002). Fazendo uso de Jsp . Nova York: Wiley. ISBN 978-0-471-21974-3., Hewitt, Eben (2003). Java para desenvolvedores Coldfusion . Upper Saddle River: Pearson Education. ISBN 978-0-13-046180-3.
  3. ^ Dixit, JB (2003). Fundamentos de computador e programação em C . Publicações Laxmi. ISBN 978-81-7008-882-0.
  4. ^ Higham, Desmond (2005). Guia MATLAB . SIAM. ISBN 978-0-89871-578-1.
  5. ^ Vermeulen, Al (2000). Os elementos do estilo Java . Cambridge University Press. ISBN 978-0-521-77768-1.
  6. ^ a b c "Usando o comentário certo em Java" . 04/03/2000 . Página visitada em 2007-07-24 .
  7. ^ WR, Dietrich (2003). Reconhecimento de padrões aplicados: algoritmos e implementação em C ++ . Springer. ISBN 978-3-528-35558-6.oferece pontos de vista sobre o uso adequado de comentários no código-fonte. p. 66
  8. ^ a b Keyes, Jessica (2003). Manual de engenharia de software . CRC Press. ISBN 978-0-8493-1479-7.discute comentários e a "Ciência da Documentação" p. 256.
  9. ^ a b c Os elementos do estilo de programação , Kernighan e Plauger
  10. ^ a b Código completo , McConnell
  11. ^ Spinellis, Diomidis (2003). Leitura de código: a perspectiva do código aberto . Addison-Wesley. ISBN 978-0-201-79940-8.
  12. ^ "CodePlotter 1.6 - Adicione e edite diagramas em seu código com esta ferramenta 'semelhante ao Visio'" . Arquivado do original em 14/07/2007 . Página visitada em 2007-07-24 .
  13. ^ a b Niederst, Jennifer (2006). Web Design em poucas palavras: Uma referência rápida sobre a área de trabalho . O'Reilly. ISBN 978-0-596-00987-8.Às vezes, a diferença entre um "comentário" e outros elementos de sintaxe de uma linguagem de programação ou marcação envolve nuances sutis. Niederst indica uma dessas situações, afirmando: "Infelizmente, o software XML considera os comentários como informações sem importância e pode simplesmente remover os comentários de um documento antes de processá-lo. Para evitar esse problema, use uma seção XML CDATA."
  14. ^ Veja por exemplo, Wynne-Powell, Rod (2008). Mac Os X para fotógrafos: Fluxo de trabalho de imagem otimizado para o usuário Mac . Oxford: Focal Press. ISBN 978-0-240-52027-8. página 243
  15. ^ Cordeiro, Linda (1998). Aprendendo o Editor VI . Sebastopol: O'Reilly & Associates. ISBN 978-1-56592-426-0. descreve o uso da sintaxe modeline nos arquivos de configuração do Vim.
  16. ^ Veja, por exemplo, Berlim, Daniel (2006). Subversion prático, segunda edição . Berkeley: APress. ISBN 978-1-59059-753-8. página 168.
  17. ^ Ambler, Scott (2004). The Object Primer: Agile Model-Driven Development com UML 2.0 . Cambridge University Press. ISBN 978-1-397-80521-8.
  18. ^ Definição de função com docstring em Clojure
  19. ^ Murach. C # 2005 . p. 56
  20. ^ c2: HotComments
  21. ^ "class Encoding" . Ruby . ruby-lang.org . Página visitada em 5 de dezembro de 2018 .
  22. ^ "PEP 263 - Definindo Codificações do Código-Fonte do Python" . Python.org . Página visitada em 5 de dezembro de 2018 .
  23. ^ Polacek, Marek (2017-03-10). "- Queda simplificada no GCC 7" . Desenvolvedor Red Hat . Red Hat . Página visitada em 10 de fevereiro de 2019 .
  24. ^ "Microsoft Programmers Hid A Bunch Of Profanity In Early Software Code" , Lisa Eadicicco, 27 de março de 2014, businessinsider.com.au
  25. ^ (consulte, por exemplo, Linux Swear Count ).
  26. ^ Goodliffe, Pete (2006). Code Craft . São Francisco: No Starch Press. ISBN 978-1-59327-119-0.
  27. ^ Smith, T. (1991). Princípios e técnicas de programação intermediária usando Pascal . Belmont: West Pub. Co. ISBN 978-0-314-66314-6.
  28. ^ Veja, por exemplo, Koletzke, Peter (2000). Oracle Developer Advanced Forms & Reports . Berkeley: Osborne / McGraw-Hill. ISBN 978-0-07-212048-6. página 65.
  29. ^ "Pior prática - comentários ruins" . Página visitada em 2007-07-24 .
  30. ^ Morelli, Ralph (2006). Java, Java, Java: resolução de problemas orientada a objetos . Prentice Hall College. ISBN 978-0-13-147434-5.
  31. ^ a b "Como escrever comentários de documentos para a ferramenta Javadoc" . Página visitada em 2007-07-24 .As diretrizes do Javadoc especificam que os comentários são cruciais para a plataforma. Além disso, o nível apropriado de detalhe é bastante bem definido: "Nós gastamos tempo e esforço focados na especificação de condições de limite, intervalos de argumentos e casos extremos, em vez de definir termos de programação comuns, escrever visões gerais conceituais e incluir exemplos para desenvolvedores."
  32. ^ Yourdon, Edward (2007). Técnicas de Estrutura e Design do Programa . Universidade de Michigan. 013901702X.Comentários inexistentes podem dificultar a compreensão do código, mas os comentários podem ser prejudiciais se forem obsoletos, redundantes, incorretos ou tornarem mais difícil compreender a finalidade pretendida para o código-fonte.
  33. ^ Dewhurst, Stephen C (2002). Pegadinhas de C ++: Evitando problemas comuns em codificação e design . Addison-Wesley Professional. ISBN 978-0-321-12518-7.
  34. ^ "Estilo de codificação" . Arquivado do original em 2007-08-08 . Página visitada em 2007-07-24 .
  35. ^ "Allen Holub" . Arquivado do original em 20/07/2007 . Página visitada em 2007-07-24 .
  36. ^ Allen Holub, Enough Rope to Shoot Yourself in the Foot , ISBN 0-07-029689-8 , 1995, McGraw-Hill 
  37. ^ Ken Thompson. "Referência do usuário a B" . Recuperado em 21-07-2017 .
  38. ^ "PEP 0350 - Codetags" , Python Software Foundation
  39. ^ "Nunca se esqueça de nada antes, depois e durante a codificação" , usando comentários de "codetag" como remanescentes produtivos
  40. ^ "Usando a Lista de Tarefas" , msdn.microsoft.com
  41. ^ "Deixe um comentário no running-config" . Cisco Learning Network (fórum de discussão) .
  42. ^ "Guia de configuração de arquivos de configuração de gerenciamento, Cisco IOS XE versão 3S (série ASR 900)" .
  43. ^ "Programação literária" . haskell.org .
  44. ^ "Programação em Lua 1.3" . www.Lua.org . Página visitada em 2017-11-08 .
  45. ^ macros.extractDocCommentsAndRunnables
  46. ^ "Comentários" . www.freepascal.org . Recuperado em 20/09/2017 .
  47. ^ "perlpod - o formato de documentação simples e antigo" . Página visitada em 2011-09-12 .
  48. ^ "Pod :: ParseUtils - ajudantes para análise e conversão POD" . Página visitada em 2011-09-12 .
  49. ^ a b "Documentação Perl 6 - Sintaxe (comentários)" . Recuperado em 06-04-2017 .
  50. ^ a b "Sintaxe básica do Python 3" . Página visitada em 25 de fevereiro de 2019 . As aspas triplas são tratadas como strings regulares, com a exceção de que podem abranger várias linhas. Por strings regulares, quero dizer que, se não forem atribuídas a uma variável, serão imediatamente coletadas como lixo assim que o código for executado. portanto, não são ignorados pelo intérprete da mesma forma que #a comentário é.
  51. ^ "Dica de Python: você pode usar strings de várias linhas como comentários de várias linhas" , 11 de setembro de 2011, Guido van Rossum
  52. ^ Talmage, Ronald R. (1999). Microsoft SQL Server 7 . Publishing Prima. ISBN 978-0-7615-1389-6.
  53. ^ "Manual de referência do MySQL 8.0" . Oracle Corporation . Recuperado em 2 de janeiro de 2020 .
  54. ^ "SQL como compreendido pelo SQLite" . Consórcio SQLite . Recuperado em 2 de janeiro de 2020 .
  55. ^ "Documentação do PostgreSQL 10.11" . Grupo de desenvolvimento global PostgreSQL . Recuperado em 2 de janeiro de 2020 .
  56. ^ "Referência SQL do banco de dados Oracle®" . Oracle Corporation . Recuperado em 2 de janeiro de 2020 .
  57. ^ Andress, Mandy (2003). Sobrevivendo à segurança: como integrar pessoas, processos e tecnologia . CRC Press. ISBN 978-0-8493-2042-2.

Outras leituras

Ligações externas