コメント(コンピュータプログラミング)

プロローグコメントが赤色で示され、インラインコメントが緑色で示されたJavaソース コードの図プログラムコードは青色です

コンピュータ プログラミングにおいてコメントとは、コンピュータ プログラムソース コード内のプログラマが判読できる説明または注釈です。これらは、ソース コードを人間が理解しやすくする目的で追加され、通常はコンパイラインタプリタによって無視されます。[1] [2]さまざまなプログラミング言語のコメントの構文は大きく異なります。

コメントは、ドキュメント ジェネレーターによってソース コード自体の外部にドキュメントを生成するため、またはソース コード管理システムや他の種類の外部プログラミング ツールとの統合に使用されるために、さまざまな方法で処理されることもあります。

コメントによってもたらされる柔軟性により、広範囲の変動が可能になりますが、その使用に関する正式な規則は、通常、プログラミング スタイルガイドの一部です。

概要

コメントは通常、ブロック コメント(プロローグ コメントまたはストリーム コメントとも呼ばれます) または行コメント(インライン コメントとも呼ばれます) のいずれかとしてフォーマットされます。[3]

ブロック コメントは、複数行または 1 行の一部にまたがるソース コードの領域を区切ります。この領域は開始デリミタと終了デリミタで指定されます一部のプログラミング言語 ( MATLABなど) では、ブロック コメントを相互に再帰的に入れ子にすることができますが、他のプログラミング言語 ( Javaなど) では許可されません。[4] [5] [6]

行コメントは、コメント区切り文字で始まり行の終わりまで続くか、場合によっては、ソース コード内の特定の列 (文字行オフセット) で始まり、行の終わりまで続きます。[6]

一部のプログラミング言語では、異なるコメント区切り文字を使用してブロック コメントと行コメントの両方を使用します。たとえば、C++ には、複数行にまたがる と で区切られたブロック コメント/*と、*/で区切られた行コメントがあります//他の言語では、1 種類のコメントのみがサポートされます。たとえば、Adaコメントは行コメントです。行の先頭から--行の末尾まで続きます。[6]

用途

コメントをどのように活用するのが最適かについては議論の余地があります。さまざまな解説者が、さまざまな、そして時には反対の視点を提供しています。[7] [8] コメントの書き方にはさまざまな方法があり、多くのコメンテーターは相反するアドバイスを提供します。[8]

計画と検討

コメントは、実際のコードを記述する前に意図を概説するための疑似コードの形式として使用できます。この場合、コード自体ではなく、コードの背後にあるロジックを説明する必要があります。

/* サーバーから返されたすべての要素を逆方向にループします
(時系列に処理する必要があります)*/ 
for ( i = ( numElementsReturned - 1 ); i >= 0 ; i -- ) { /* 各要素のデータを処理します */ updatePattern ( i returnedElements [ i ]); }          
    
     

このタイプのコメントが残されている場合、コードと意図した結果を直接比較できるため、レビュー プロセスが簡素化されます。よくある論理的誤謬は、理解しやすいコードは本来の動作を行うというものです。

コードの説明

コメントは、コードを要約したり、プログラマーの意図を説明したりするために使用できます。この考え方によれば、コードを平易な英語で言い換えることは不必要であると考えられます。コードを再説明する必要があるということは、コードが複雑すぎて書き直す必要があること、または名前付けが間違っていることを示している可能性があります。

「悪いコードを文書化するのではなく、書き直してください。」[9]
「良いコメントは、コードを繰り返したり、説明したりするものではありません。コードの意図を明確にします。コメントは、コードよりも高い抽象レベルで、何をしようとしているのかを説明する必要があります。」[10]

コメントは、コード ブロックが規則やベスト プラクティスに適合しないと思われる理由を説明するために使用することもできます。これは、開発時間が非常に短いプロジェクトやバグ修正に特に当てはまります。例えば:

' フォーム データを再利用するときにサーバー エラーが発生したため、2 番目の変数 dim が発生しました。' サーバーの動作の問題に関するドキュメントは利用できない
ため、その問題をコーディングするだけです。
vtx =サーバーマップパス( "ローカル設定" )  

アルゴリズムの説明

ソース コードには、特定の問題に対する斬新な解決策や注目に値する解決策が含まれている場合があります。そのような場合、コメントには方法論の説明が含まれる場合があります。このような説明には、図や正式な数学的証明が含まれる場合があります。これは、コードの意図の明確化ではなく、コードの説明を構成する場合があります。しかし、コード ベースの保守を担当する人にとっては、そのような説明が重要であると感じるかもしれません。これは、高度に専門化された問題領域の場合に特に当てはまります。または、めったに使用されない最適化、構築、または関数呼び出し。[11]

たとえば、プログラマは、理論上、クイックソートの代わりに挿入ソートが選択された理由を説明するコメントを追加できます。これは、理論上、挿入ソートの方が後者よりも遅いからです。これは次のように書くことができます。

 リスト= [ f ( b ), f ( b ), f ( c ), f ( d ), f ( a ), ... ] ; // 安定したソートが必要です。それに、パフォーマンスは本当に重要ではありません。挿入ソート(リスト);            
 
  

リソースの包含

ASCII アート構造で構成されるロゴ、図、フローチャートをコメント形式のソース コードに挿入できます。[12]さらに、著作権表示をソース コード内にコメントとして埋め込むことができます。バイナリ データは、バイナリからテキストへのエンコードと呼ばれるプロセスを通じてコメント内でエンコードされることもありますが、そのような方法は一般的ではなく、通常は外部リソース ファイルに限定されます。

次のコード部分は、 Windows スクリプト ホストで実行されるWindows スクリプト ファイルに含まれるシステム管理スクリプトのプロセス フローを示す単純な ASCII 図ですコードをマークするセクションはコメントとして表示されますが、図自体は実際にはXML CDATAセクションに表示されます。これは技術的にはコメントとは異なるものとみなされますが、同様の目的を果たすことができます。[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> 











この同一の図はコメントとして簡単に含めることができますが、この例は、プログラマがソース コードにリソースを含める方法としてコメントを使用しないことを選択する可能性がある 1 つの例を示しています。[13]

メタデータ

コンピューター プログラム内のコメントには、プログラム ファイルに関するメタデータが保存されることがよくあります。

特に、多くのソフトウェア管理者は、そのプログラムのソース コードを読んだ人が改善点を管理者に送信できるように、コメントに提出ガイドラインを記載しています。

その他のメタデータには、プログラム ファイルの元のバージョンの作成者の名前と最初のバージョンが作成された日付、プログラムの現在の管理者の名前、これまでにプログラム ファイルを編集した他の人の名前が含まれます。 、プログラムの使用方法に関するドキュメントの URL、このプログラム ファイルのソフトウェア ライセンスの名前など。

プログラムの一部のセクションのアルゴリズムが書籍またはその他の参考文献の説明に基づいている場合、コメントを使用して書籍のページ番号とタイトル、またはコメント要求またはその他の参考文献を指定できます。

デバッグ

開発者の一般的な手法は、コード スニペットをコメント アウトすることです。つまり、コメント構文を追加して、そのコード ブロックがコメントになり、最終プログラムで実行されないようにすることです。これは、最終的なプログラムから特定のコード部分を除外するために行われる場合もあれば、(より一般的には) エラーの原因を見つけるために使用される場合もあります。プログラムの一部を系統的にコメントアウトして実行することで、エラーの原因を特定し、修正できるようになります。

多くの IDE では、単一のメニュー オプションまたはキーの組み合わせを使用して、このようなコメントをすばやく追加または削除できます。プログラマは、コメント化 (解除) したいテキストの部分をマークし、適切なオプションを選択するだけで済みます。

ドキュメントの自動生成

プログラミング ツールは、ドキュメントやメタデータをコメントに保存することがあります。[14]これらには、ヘッダー ファイルを自動的に組み込むための挿入位置、ファイルの構文強調表示モードを設定するコマンド、 [15]またはファイルのリビジョン番号が含まれる場合があります。[16]これらの機能制御コメントは、一般にアノテーションとも呼ばれますソース コードのコメント内にドキュメントを保持することは、ドキュメントのプロセスを簡素化し、コードの変更に応じてドキュメントが最新の状態に保たれる可能性を高める 1 つの方法と考えられます。[17]

ドキュメント ジェネレーターの例には、 Javaで使用するプログラムJavadocD用のDdocCC++、 Java 、IDL用のDoxygenPL/SQL用のVisual ExpertTransact-SQLPowerBuilder、およびPHP用のPHPDocなどのプログラムが含まれます。docstringの形式は、PythonLispElixir、およびClojureでサポートされています[18]

C#F#、およびVisual Basic .NET は、コンパイルされた.NETアセンブリからIntelliSenseによって読み取られる「XML コメント」と呼ばれる同様の機能を実装しています[19]

構文拡張

場合によっては、もともとコメントであることを意図していた構文要素が、「条件付きコメント」など、プログラムに追加情報を伝えるために再利用されることがありますこのような「熱いコメント」は、下位互換性を維持する唯一の実用的な解決策である可能性がありますが、広くはクラッジとみなされています。[20]

ディレクティブの使用法

エディターまたはインタープリター用の特別なディレクティブを作成するために、通常のコメント文字が使用される場合があります

インタプリタを指示する 2 つの例は次のとおりです。

  • Unix の「shebang」 – #!– 使用するインタプリタを指すためにスクリプトの最初の行で使用されます。
  • ソース ファイルが使用しているエンコーディングを識別する「マジック コメント」。[21]例: Python の PEP 263。[22]

Unix 系システム用の以下のスクリプトは、これらの使用法の両方を示しています。

#!/usr/bin/env python3 
# -*- コーディング: UTF-8 -*- 
print ( "テスト" )

C でコメントを使用して、 case ステートメントのデフォルトの「フォールスルー」が意図的に行われたこと をコンパイラーに伝える場合も、ある程度似ています。

スイッチ(コマンド) {  
    CMD_SHOW_HELP_AND_EXITの場合: 
      do_show_help ();
      /* フォールスルー */
    CMD_EXITの場合: 
      do_exit ();
      壊す;
    ケースCMD_OTHER : 
      do_other ();
      壊す;
    /* ... など ... */
  }

人間の読者向けにこのようなコメントを挿入することは/* Fall thru */すでに一般的な慣例でしたが、2017 年にgccコンパイラーはこれら (または意図的な意図を示すその他の兆候) を探し始め、見つからない場合は「警告: このステートメントは失敗する可能性があります」と表示します。[23]

多くのエディターやIDE は、特別にフォーマットされたコメントを読み取ります。たとえば、Vimの「モードライン」機能。これにより、ファイルの先頭近くに次のコメントが含まれるソース編集中のタブの処理が変更されます。

# vim: タブストップ=8 拡張タブ シフト幅=4 ソフトタブストップ=4

応力緩和

プログラマーは、ストレスを軽減する方法として、開発ツール、競合他社、雇用主、労働条件、またはコード自体の品質についてコメントを追加することがあります。[24]この現象の発生は、ソース コード内の冒涜を追跡するオンライン リソースから簡単に確認できます。[25]

規範的な見解

ソース コード内でのコメントの適切な使用に関しては、さまざまな規範的な見解や長年の意見があります。[26] [27]これらの一部は非公式で個人的な好みに基づいていますが、その他は特定のコミュニティ向けの正式なガイドラインとして公開または公布されています。[28]

コメントの必要性

ソース コード内でコメントが適切かどうか、またいつ適切かについては、専門家によってさまざまな見解があります。[9] [29]ソース コードは一目瞭然、または自己文書化されるべきであるとして、ソース コードはほとんどコメントを付けずに書かれるべきだと主張する人もいます[9]コードを広範囲にコメント化する必要があると提案する人もいます (ソース コード内の非空白文字の 50% 以上がコメント内に含まれることは珍しいことではありません)。[30] [31]

これらの見解の間には、コメントはそれ自体では有益でも有害でもない、重要なのはコメントが正確であり、ソースコードとの同期が保たれていることであり、コメントが不必要、過剰、保守が困難、あるいは役に立たない場合には省略される、という主張があります。[32] [33]

コメントは、プログラミングに対する 契約ごとの設計アプローチで契約を文書化するために使用されることがあります。

詳細度

コードの対象読者やその他の考慮事項に応じて、詳細と説明のレベルは大幅に異なる場合があります。

たとえば、次の Java コメントは、プログラミングの初心者を教えることを目的とした入門テキストに適しています。

文字列s = "ウィキペディア" ; /* 値「Wikipedia」を変数 s に代入します。*/    

ただし、この詳細レベルは、運用コードのコンテキストや、経験豊富な開発者が関与するその他の状況では適切ではありません。このような初歩的な記述は、「良いコメント…意図を明確にする」というガイドラインと矛盾します。[10]さらに、プロフェッショナルなコーディング環境では、通常、ビジネス運営によって定義された特定のパフォーマンス要件を満たすために詳細レベルが明確に定義されます。[31]

スタイル

ソース コード内でコメントをどのように表示するかを検討する場合、多くのスタイル上の代替案が利用できます。開発者チームが関与する大規模なプロジェクトの場合、コメントのスタイルはプロジェクトの開始前に合意されるか、慣例やプロジェクトの成長に応じて必要に応じて進化します。通常、プログラマーは、一貫性があり、邪魔にならず、変更が容易で、壊れにくいスタイルを好みます。[34]

コメントをブロックする

次の C のコード部分は、同じ基本情報を伝えながら、コメントのスタイルがどのように変化するかを示すほんの小さな例を示しています。

/*
     これはコメントの本文です。
     バリエーション1。
*/
/****************************\ 
* * 
* コメント本文です。* 
* バリエーション 2。* 
* * 
\***************************/

個人の好み、プログラミング ツールの柔軟性、その他の考慮事項などの要因が、ソース コードで使用されるスタイルのバリエーションに影響を与える傾向があります。たとえば、バリエーション 2 は、コメント内のテキストの配置や見た目を自動化できる ソース コード エディタを持たないプログラマの間では好まれない可能性があります。

ソフトウェア コンサルタントで技術解説者のアレン ホルブ[35]は、コメントの左端を揃えることを提唱する専門家の 1 人です。[36]

 /* これは、Holub が C および C++ に対して推奨するスタイルです。
  * これは、ルール 29 の「十分なロープ」で実証されています。
  */
 /* これは、C でも行う別の方法です。 **
コメントの 2 行目から最後の行までを、最初の行から 1 行分のスペースで自動的にインデントしないエディターで行う方が簡単です。
** これはホルブの本のルール 31 でも使用されています。*/


ブロック コメント区切り文字としての /* および */ の使用は、PL/I から C プログラミング言語の直前の前身である B プログラミング言語に継承されました。[37]

行コメント

行コメントは通常、任意の区切り文字または一連のトークンを使用してコメントの開始を示し、改行文字を使用してコメントの終了を示します。

この例では、ASCII 文字 // から行末までのすべてのテキストが無視されます。

// ------------------------ 
// これはコメント本文です。
// ------------------------

多くの場合、そのようなコメントは左端から始めて行全体に拡張する必要があります。ただし、多くの言語では、次の Perl の例のように、コマンド ラインのインラインにコメントを配置して、それにコメントを追加する こともできます。

$sを印刷します"\n" ; # 印刷後に改行文字を追加する        

言語で行コメントとブロック コメントの両方が許可されている場合、プログラミング チームは、行コメントとブロック コメントを異なる方法で使用する規則を決定することがあります。たとえば、行コメントは軽微なコメントにのみ使用し、ブロック コメントはより高いレベルの抽象概念を記述するために使用します。

タグ

プログラマーは、一般的な問題のインデックス付けを支援するために、コメント内で非公式のタグを使用する場合があります。Unix grepユーティリティなどの一般的なプログラミング ツールを使用して検索したり、テキスト エディタ内で構文を強調表示したりすることもできますこれらは「コードタグ」 [38] [39]または「トークン」と呼ばれることもあり、開発ツールはそれらをすべてリストするのに役立つ場合もあります。[40]

このようなタグは大きく異なりますが、次のものが含まれる場合があります。

  • BUG、DEBUG —修正する必要がある既知のバグ。
  • FIXME — 修正する必要があります。
  • ハック、ボッジ、クラッジ — 回避策。
  • TODO — やるべきこと。
  • 注 — 特に注目すべき問題点を強調するために使用されます。
  • UNDONE — 以前のコードを元に戻す、または「ロールバック」します。
  • XXX — 問題のあるコードまたは誤解を招くコードについて他のプログラマーに警告する

比較

コメントを指定するための表記規則は大きく異なります。さらに、個々のプログラミング言語が独自のバリアントを提供する場合があります。

エイダ

Adaプログラミング言語で、行末までのコメントを示すために「--」を使用します。

例えば:

  -- 航空管制官タスクは、離陸および着陸のリクエストを受け取ります。
   タスク タイプ コントローラ ( My_Runway : Runway_Access )は -- 同期メッセージ パッシング エントリRequest_Takeoff ( ID : in Airplane_ID ; Takeoff : out Runway_Access )のタスク エントリです。
      エントリRequest_Approach ( ID : in Airplane_ID ; Approach : out Runway_Access ); エンドコントローラー;
           
          
    

APL

APL は、行末までのコメントを示すために 使用します。

例えば:

⍝ 次に数値を加算します: 
c a + b ⍝ 加算 

("left") および("right") プリミティブを持つ方言では、コメントは多くの場合、無視される文字列の形式で ステートメント内または別のステートメントに含めることができます。

d 2 × c 'どこで' c a + '境界' b    

AppleScript

AppleScriptコードのこのセクションでは、その言語で使用される 2 つのスタイルのコメントを示します。

(*このプログラム
挨拶を表示します。
*)
挨拶 ( myGreeting )表示ダイアログmyGreeting & " world!" 終わりの挨拶
        
 

-- 挨拶
( こんにちは」)を表示します。

ベーシック

この古典的な初期のBASICコード フラグメントでは、REM ( "Remark" ) キーワードを使用してコメントを追加しています。

10 REM この BASIC プログラムは、PRINT ステートメントと GOTO ステートメントの使用法を示します。15 REM 画面いっぱいに「HELLO」というフレーズが表示されます20 PRINT 「HELLO」30 GOTO 20 
 
  
  

以降のMicrosoft BASIC ( Quick BasicQ BasicVisual BasicVisual Basic .NET、およびVB Scriptを含む) では、また、 FreeBASICGambasなどの子孫では、行内の ' (アポストロフィ) 文字の後のテキストもコメントとして扱われます。

Visual Basic .NET の例:

Public Class Form1 Private Sub Button1_Click ( sender As Object e As EventArgs ) Button1を処理しますクリック' ユーザーがプログラムのウィンドウ内のボタンをクリックすると、 ' 次のコードが実行されます。レムのコメントはまだ残っています。  
             
        
        
        

        メッセージボックスShow ( "Hello, World" ) ' 挨拶を含むポップアップ ウィンドウを表示End Sub End Class 
     
 

C

このCコードの断片は、条件文の目的を説明するためのプロローグ コメントまたは「ブロック コメント」の使用法を示していますコメントでは重要な用語と概念が説明されており、コードを作成したプログラマーによる短い署名が含まれています。

 /* 
  * 最大プロセス制限を超えているかどうかを確認しますが、必ず
  * root を除外してください。
  これは、ログインおよび* フレンドがユーザーごとのプロセス制限を、
  root が実行しているプロセスの量より *低い値に設定
できるようにするために必要です。-- Rik   */ 
if ( atomic_read ( & p -> user -> processes ) >= p -> rlim [ RLIMIT_NPROC ]. rlim_cur && !対応( CAP_SYS_ADMIN ) && !対応可能( CAP_SYS_RESOURCE )) goto bad_fork_free ;    
        
      

C99 以降、単一行コメントを示す C++ の // 構文も使用できるようになりました。


ブロック コメントを利用できるため、次の例のように、 構造的ブレークアウト、つまり構造化プログラミング のシングルエントリー/シングルイグジットのルールの許容される違反を視覚的にマークすることができます。

static Edgeedge_any ( Node n , Node m ) { // ノード $n と $m の間にエッジがあるかどうかを返しますエッジe ; for ( e = n ->エッジ; e ; e = e -> next ) { if ( e -> dst == m ) { /*********/ return e ; } } for ( e = m ->エッジ; e ; e = e -> next ) { if ( e -> dst == n ) { /*****/ break ; e返します}      
    
     
        
            
    
        
            
       
      

ブロック コメントのない多くの言語 (例: awk )では、代わりに のような一連のステートメント区切り文字を使用できます;しかし、 Pythonのように、意図したブロック構造を厳密に示すためにインデントを使用する言語ではそれは不可能です

Cisco IOS および IOS-XE の構成

Cisco ルータの設定モードでコメントをマークするために感嘆( ! ) を使用できますが、そのようなコメントは不揮発性メモリ(startup-config を含む)には保存されず、「show run」コマンドでも表示されません。 。[41] [42]

実際に構成の一部である人間が判読可能なコンテンツを挿入することは可能であり、次の方法でNVRAMスタートアップ構成 に保存できます。

  • 「description」コマンドは、インターフェイスまたはBGPネイバーの設定に説明を追加するために使用されます。
  • 「name」パラメータ。静的ルートにコメントを追加します。
  • アクセスリストの「remark」コマンド
トラフィックを手動で再ルーティングするには、以下のテキストを貼り付けます
設定
int gi0/2
いいえ、閉じません
ip ルート 0.0.0.0 0.0.0.0 gi0/2 名前 ISP2
no ip ルート 0.0.0.0 0.0.0.0 gi0/1 名前 ISP1
int gi0/1
シャット
出口

コールドフュージョン

ColdFusion では、 HTML コメントと同様のコメントを使用しますが、2 つのダッシュの代わりに 3 つのダッシュを使用します。これらのコメントは ColdFusion エンジンによって捕捉され、ブラウザには出力されません。

このようなコメントは入れ子にすることができます。

 <!--- これにより、ブラウザに「Hello World」が出力されます。
   <!--- これは最初のコメント内で使用されるコメントです。
   ---> 
---> 
 <cfoutput> 
   Hello World < br  /> 
 </cfoutput>

D

D では、 C++ スタイルのコメントと、「/+」で始まり「+/」で終わる入れ子可能な D スタイルの複数行コメントが使用されます。

// これは 1 行のコメントです。
/* これは複数行のコメントです。

*/ 
/+ これは
  /+ ネストされた +/
    コメントです +/

フォートラン IV

このFortran IVコードの断片は、非常に列指向の言語でコメントがどのように使用されるかを示しています。列 1 に文字「C」を指定すると、行全体がコメントとして扱われます。

C 
C 「C」で始まる行 (最初の列または「コメント」列) はコメントです
C 
WRITE ( 6 , 610 )   610 FORMAT ( 12 H HELLO WORLD ) END       
   
      

それ以外の場合、行の列は 4 つのフィールドとして扱われることに注意してください。1 ~ 5 はラベル フィールドで、6 では行が前のステートメントの継続として扱われます。宣言とステートメントは 7 から 72 に入ります。

フォートラン90

このFortranコード フラグメントは、その言語でコメントがどのように使用されるかを示しており、コメント自体が基本的な書式設定ルールを記述しています。

!* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * ! 
* 感嘆符の後のすべての文字はコメントとみなされます * 
!* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *プログラム comment_test print '( 
A ) 
' , ' Hello world' Fortran 90 では、インライン コメントのオプションが導入されました。プログラムを終了する       

ハスケル

Haskell の行コメントは '--' (2 つのハイフン) で始まり行末まで続き、複数行のコメントは '{-' で始まり '-}' で終わります。


{- これは複数行の
コメントです-} -- これは 1 行のコメントです
putStrLn "Wikipedia" -- これは別のコメントです   

Haskell は、 「バード スタイル」として知られるコメントのプログラミング手法も提供します。[43]この例では、> で始まるすべての行がコードとして解釈され、それ以外はすべてコメントとみなされます。追加の要件の 1 つは、コード ブロックの前後に常に空白行を残すことです。

Bird スタイルでは、コードの前に空白を残す必要があります。

>ファクト::整数->整数>ファクト0 = 1 >ファクト( n + 1 ) = ( n + 1 ) *ファクトn    
   
      

コードの後に​​も空白行を残す必要があります。

LaTeXを使用して、Haskell で読み書き可能なプログラミングを行うこともできますRichard Bird スタイルの代わりにコード環境を使用できます。LaTeXスタイルでは、これは上記の例と同等であり、コード環境は LaTeX プリアンブルで定義できます。簡単な定義は次のとおりです。

\usepackage {逐語} 
\newenvironment {コード}{ \verbatim }{ \endverbatim }

後で

% LaTeX ソース ファイル
\ verb |fact n| 関数呼び出しは$ nを計算します! $ if $ n \ge 0 $、ここに定義があります: \\ \begin { code } fat :: Integer -> Integer fat 0 = 1 fat ( n + 1 ) = ( n + 1 ) * fat n \end { \LaTeX {}マークアップを
使用
した詳細な説明は次のとおりです 

    
   
      

ジャワ

このJavaコードの断片は、メソッドの説明に使用されるブロック コメントを示していますsetToolTipTextフォーマットは、Sun Microsystems Javadoc標準と一致しています。コメントは Javadoc プロセッサによって読み取られるように設計されています。

/** 
* Java のブロック コメントです。
※ setToolTipTextメソッドはツールチップに表示するテキストを登録します。
※コンポーネント上にカーソルを置くとテキストが表示されます。
* 
* @param text 表示する文字列。'text' が null の場合、
* このコンポーネントのツールチップはオフになります。
*/ 
public void setToolTipText ( String text ) { // これは Java のインライン コメントです。TODO: このメソッドのコードを作成します。}    
    

JavaScript

JavaScript では、コメントの前に // を使用し、複数行のコメントには /* */ を使用します。

// 単一行の JavaScript コメント
var iNum = 100 ; var iTwo = 2 ; // 行末のコメント/*複数行のJavaScript コメント*/   
    




ルア

Luaプログラミング言語は、 AdaEiffelHaskellSQLおよびVHDL--言語と同様に、単一行のコメントに二重ハイフン を使用しますLua にはブロック コメントもあり、コメントは終了まで続きます。--[[]]

例えば:

--[[複数行の
長いコメント
]] 
print ( 20 )    -- 結果を出力します。

コードの一部をコメント アウトする一般的な手法[44]は、以下のように コードを--[[と で囲むことです。--]]

--[[ 
print(10) 
--]] 
-- アクションなし (コメントアウト)

この場合、最初の行にハイフンを 1 つ追加することでコードを再度アクティブにすることができます。

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

最初の例では、--[[最初の行の は長いコメントを開始しており、最後の行の 2 つのハイフンはまだそのコメント内にあります。2 番目の例では、シーケンスは---[[通常の単一行​​のコメントを開始するため、最初の行と最後の行が独立したコメントになります。この場合、 はprintコメント外です。この場合、最後の行は で始まるため、独立したコメントになります--

Lua の長いコメントは、 「Lua でのプログラミング」の「長い文字列」と呼ばれるセクションで読むことができるように、これらよりも複雑になる可能性があります

MATLAB

MATLABのプログラミング言語では、「%」文字は単一行のコメントを示します。複数行のコメントは、%{ および %} 括弧を介して使用することもでき、ネストすることもできます。

% これらは各項の導関数です。
d = [ 0 - 1 0 ];    

%{ 
  %{ 
    (ネストされたコメントの例。インデントは装飾用です (無視されます)。) 
% }  テイラー
公式に従ってシーケンス形成ますベクトル操作していること注意してください%} seq = d .* ( x - c ) .^ n ./ (階乗( n ))         
        

       

% 合計してテイラー近似を取得します
近似= sum ( seq )  

ニム

Nim はインライン コメントに「#」文字を使用します。複数行のブロック コメントは「#[」で開き、「]#」で閉じます。複数行のブロック コメントは入れ子にすることができます。

Nim には、Markdown マークアップReStructuredTextマークアップを混合して使用するドキュメント コメントもあります。インラインのドキュメント コメントは '##' を使用し、複数行のブロック ドキュメント コメントは '##[' で開き、']##' で閉じます。コンパイラーは、ドキュメントのコメントからHTMLLaTeX、およびJSONドキュメントを生成できます。ドキュメントのコメントは抽象構文ツリーの一部であり、マクロを使用して抽出できます。[45]

## モジュール *ReSTRucturedText* および **MarkDown** のドキュメント
# これはコメントですが、ドキュメント コメントではありません。

type Kitten = object ## age : int型のドキュメント## フィールドのドキュメント     
     

proc purr ( self : Kitten ) = ## 関数echo "Purr Purr"のドキュメント# これはコメントですが、ドキュメントのコメントではありません。   
  
     

# これはコメントですが、ドキュメントのコメントではありません。

OCaml

OCaml はネスト可能なコメントを使用します。これは、コード ブロックをコメントするときに便利です。

codeLine (* コメントレベル 1(*コメントレベル 2*)*)

パスカル、デルフィ

PascalDelphiでは、コメントは「{ ... }」で区切られます。コメント行は '\\' で始めることもできます。これらの文字をサポートしていないコンピュータの場合は、代わりに「(* ... *)」を使用できます。[46]

Niklaus Wirthのより現代的な言語ファミリー ( Modula-2Oberonを含む)では、コメントは '(* ... *)' で区切られます。[47] [48]

例えば:

(* 対角線のテスト *) 
columnDifference := testColumn -; if (+列の差= testRow )または......    
      
    

コメントは入れ子にすることができます。// は {} に含めることができ、{} は (**) に含めることができます。

パール

Perlや他の多くのスクリプト言語の行コメントは、ハッシュ (#) 記号で始まります。

# 簡単な例
# 
my $s = "Wikipedia" ; # 変数 s を「Wikipedia」に設定します。$sを印刷します"\n" ; # 印刷後に改行文字を追加する    
        

通常のブロック コメント構造の代わりに、Perl は、読み書き可能なプログラミング用のマークアップ言語であるPlain Old Documentationを使用します[49]たとえば、次のようになります。

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

新しいリスト オブジェクトを作成します。プロパティは、次のようにハッシュ参照を通じて指定できます


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

詳細については、個々のメソッド/プロパティを参照してください。

=カット

サブ新しい{ my $this =シフト; 私の$class = ref ( $this ) || $this ; 私の%params = @_ ; 私の$self = { %params }; $self $classを祝福してください$self ->初期化(); $selfを返します}  
       
         
       
       
      
    
     

R

R は、ハッシュ (#) 文字で始まるインライン コメントのみをサポートします。

# これはコメントです
print ( "これはコメントではありません" ) # これは別のコメントです  

raku (以前は Perl 6 と呼ばれていました) は、通常のPerlと同じ行コメントと POD ドキュメント コメントを使用します(上記の Perl セクションを参照) が、構成可能なブロック コメント タイプ「複数行 / 埋め込みコメント」が追加されています。[51]

これらはハッシュ文字で始まり、バッククォート、次に開始括弧文字が続き、対応する終了括弧文字で終わります。[51]コンテンツは複数行にまたがるだけでなく、インラインに埋め込むこともできます。

#`{{ このバージョンを「コメントアウト」しています
toggle-case(Str:D $s)

文字列内の各文字の大文字と小文字を切り替えます。

  my Str $toggled-string = toggle-case("私の名前はマイケルです!");

}}

sub  toggle-case ( Str:D  $s ) #`( このバージョンの括弧は現在使用されています ) {
    ...
}

PHP

PHPのコメントは、C++ スタイル (インラインとブロックの両方) にすることも、ハッシュを使用することもできます。PHPDoc はJavadoc から採用されたスタイルで、PHP コードを文書化するための共通標準です。

PHP 8 以降、# 記号は、直後に「[」が続かない場合にのみコメントを意味します。それ以外の場合は、「]」まで実行される関数属性を意味します。

/** 
* このクラスにはサンプル ドキュメントが含まれています。
* 
* @author Unknown 
*/ 
#[属性] 
class  MyAttribute  { 
    const  VALUE  =  'value' ; 
    // これはインラインコメントです。C++ と同様に「//」で始まります。
    プライベート $value ; 
    # これは、「#」で始まる Unix スタイルのインライン コメントです。
    パブリック 関数 __construct ( $value  =  null )  { 
        $this -> value  =  $value ; 
    } 
    /*
    これは複数行のコメントです。

    これらのコメントはネストできません。
    */

}

パワーシェル

Windows PowerShellのコメント

# 一行コメント
Write-Host  "Hello, World!"

<# 複数
   行の
   コメント #>

書き込みホスト 「さようなら、世界!」

パイソン

このコードの 2 つの例のように、 Pythonのインライン コメントではハッシュ (#) 文字が使用されます。

# このプログラムは「Hello World」を画面に出力します
print ( "Hello World!" )   # 新しい構文に注意してください

この記事で定義されているブロック コメントは、Python には技術的には存在しません。[52]三重引用符で囲まれた文字列で表される裸の文字列リテラルも使用できます[53]が、「#」コメントと同様にインタプリタによって無視されません。[52]以下の例では、三重二重引用符で囲まれた文字列はこのようにコメントとして機能しますが、docstringとしても扱われます。

"""
これがファイル mymodule.py であると仮定すると、ファイルの最初のステートメントであるこの文字列は、
ファイルがインポートされるときに "mymodule" モジュールの docstringなります。



class  MyClass : 
"""クラスのドキュメント文字列"""    

    def  my_method ( self ): 
"""メソッドの docstring"""        

def  my_function (): 
"""関数のドキュメント文字列"""    

ルビー

Rubyのインライン コメントは# 文字で始まります。

複数行のコメントを作成するには、行の先頭に「=begin」を配置する必要があります。その後、行の先頭の「=end」まではすべて無視されます。この場合、等号の後にスペースを含めると構文エラーがスローされます。

「これはコメントではありません」を付ける 

#これはコメントです

「これはコメントではありません」を付ける 

=始まり

これらの行に含まれるものは何でも

人間の読者専用です

=終わり

「これはコメントではありません」を付ける 

SQL

SQL の標準コメントは 2 つのダッシュを使用した 1 行のみの形式です。

-- これは 1 行のコメントです
。その後に 2 行目の
SELECT COUNT ( * ) FROM Authors WHERE Authorsが続きます名前= 'スミス' ; -- 注: 必要なのは「smith」のみです-- このコメントは SQL コードの後に​​表示されます 
        
           
                                     

あるいは、C および Java の構文で使用される「ブロック コメント」スタイルと同じコメント形式構文が、Transact-SQLMySQLSQLitePostgreSQL、およびOracleでサポートされています。[54] [55] [56] [57] [58]

MySQL は、ハッシュ (#) 文字から行末までのコメントもサポートします。

迅速

単一行のコメントは 2 つのスラッシュ (//) で始まります。

// これはコメントです。

複数行のコメントは、スラッシュとそれに続くアスタリスク (/*) で始まり、アスタリスクとそれに続くスラッシュ (*/) で終わります。

/* これもコメントです
が複数行に渡って書かれています。*/

Swift の複数行コメントは、他の複数行コメント内にネストできます。ネストされたコメントを作成するには、複数行コメント ブロックを開始し、最初のブロック内で 2 番目の複数行コメントを開始します。次に 2 番目のブロックが閉じられ、続いて最初のブロックが閉じられます。

/* これは最初の複数行コメントの始まりです。
/* これは 2 番目のネストされた複数行コメントです。*/
これで最初の複数行コメントは終わりです。*/

XML (または HTML)

XML (または HTML) のコメントは次のように導入されます。

< !--

ターミネータまで複数の行にまたがる場合があります。

-->

例えば、

<!-- ここでコンテキストを選択 --> 
<param name= "context" value= "public" />   

SGMLとの互換性のため、コメント内に文字列「--」(二重ハイフン) を使用することはできません。

セキュリティ上の問題

インタープリタ言語では、コメントはプログラムのエンド ユーザーに表示されます。コードのセクションが「コメントアウト」されている場合など、場合によっては、セキュリティ上の脆弱性が発生する可能性があります。[59]

こちらも参照

メモと参考文献

  1. ^ソース コードは プログラム コード(機械翻訳可能な命令で構成される)に分割できます。およびコメント(プログラム コードをサポートする人間が読めるメモやその他の種類の注釈を含みます)。ペニー・グラブ、アームストロング・タカン (2003)。ソフトウェア メンテナンス: 概念と実践世界科学。ページ 7 から始めてください 120–121。ISBN 978-981-238-426-3
  2. ^ この記事では、プログラミング言語のコメントは、マークアップ言語設定ファイル、およびその他の同様のコンテキストに表示されるコメントと区別できないものとして扱われます。さらに、マークアップ言語は、特にコード生成のコンテキストにおいて、プログラミング言語コードと密接に統合されることがよくありますたとえば、Ganguli、Madhushree (2002) を参照してください。Jsp の利用ニューヨーク: ワイリー。ISBN 978-0-471-21974-3ヒューイット、エベン(2003)。Coldfusion 開発者向けの Javaサドル川上流: ピアソン教育。ISBN 978-0-13-046180-3
  3. ^ JB ディクシット (2003)。コンピュータの基礎と C によるプログラミングラクシュミ出版。ISBN 978-81-7008-882-0
  4. ^ ハイアム、デズモンド (2005)。MATLAB ガイドサイアム。ISBN 978-0-89871-578-1
  5. ^ フェルミューレン、アル (2000)。Java スタイルの要素。ケンブリッジ大学出版局。ISBN 978-0-521-77768-1
  6. ^ abc 「Java での正しいコメントの使用」. 2000 年 3 月 4 日2007 年 7 月 24 日に取得
  7. ^ WR、ディートリッヒ (2003)。応用パターン認識: C++ でのアルゴリズムと実装スプリンガー。ISBN 978-3-528-35558-6ソースコード内のコメントの適切な使用に関する視点を提供します。p. 66.
  8. ^ ab キーズ、ジェシカ (2003). ソフトウェア エンジニアリング ハンドブックCRCプレス。ISBN 978-0-8493-1479-7コメントと「ドキュメンテーションの科学」p.36 について説明します。256.
  9. ^ abc プログラミング スタイルの要素カーニハン&プラウガー
  10. ^ ab コード完了マコーネル
  11. ^ スピネリス、ディオミディス (2003)。コードの読み取り: オープンソースの観点アディソン・ウェスリー。ISBN 978-0-201-79940-8
  12. ^ "CodePlotter 1.6 – この「Visio のような」ツールを使用して、コードに図を追加および編集します。" 2007 年 7 月 14 日にオリジナルからアーカイブされました2007 年 7 月 24 日に取得
  13. ^ ab ニーダースト、ジェニファー (2006)。Web デザインの概要: デスクトップ クイック リファレンスオライリー。ISBN 978-0-596-00987-8「コメント」と、プログラミング言語やマークアップ言語の他の構文要素との違いには、微妙なニュアンスが伴う場合があります。Niederst 氏は、そのような状況の 1 つを次のように述べています。「残念ながら、XML ソフトウェアはコメントを重要ではない情報とみなしているため、ドキュメントを処理する前にドキュメントからコメントを削除する可能性があります。この問題を回避するには、代わりに XML CDATA セクションを使用してください。」
  14. ^ 例、Wynne-Powell、Rod (2008) を参照。写真家のための Mac OS X: Mac ユーザー向けに最適化された画像ワークフロー。オックスフォード: フォーカルプレス。p. 243.ISBN _ 978-0-240-52027-8
  15. ^ ラム、リンダ (1998). VI エディタを学習します。セバストポル: オライリー&アソシエイツ。ISBN 978-1-56592-426-0Vim 設定ファイルでのモードライン構文の使用について説明します。
  16. ^ 例えば、Berlin、Daniel (2006) を参照。実践的な Subversion、第 2 版バークレー:AP通信。p. 168.ISBN _ 978-1-59059-753-8
  17. ^ アンブラー、スコット (2004)。オブジェクト入門: UML 2.0 によるアジャイル モデル駆動開発ケンブリッジ大学出版局。ISBN 978-1-397-80521-8
  18. ^ Clojure での docstring を使用した関数定義
  19. ^ ムラッハ。C#2005p. 56.
  20. ^ c2: HotComments
  21. ^ "クラスのエンコーディング". ルビーRuby-lang.org 2018 年12 月 5 日に取得
  22. ^ "PEP 263 – Python ソース コード エンコーディングの定義". Python.org 2018 年12 月 5 日に取得
  23. ^ ポラチェック、マレク (2017-03-10)。「GCC 7 の -Wimplicit-fallthrough」。レッドハット開発者レッドハット2019 年2 月 10 日に取得
  24. ^ リサ・エアディシッコ (2014 年 3 月 27 日)。「マイクロソフトのプログラマーは初期のソフトウェア コードに大量の冒涜的な言葉を隠した」。ビジネスインサイダーオーストラリア2016年12月29日のオリジナルからアーカイブ。
  25. ^ (例: Linux Swear Count を参照)。
  26. ^ ピート・グッドリフ (2006). コードクラフトサンフランシスコ: スターチプレスはありません。ISBN 978-1-59327-119-0
  27. ^ スミス、T. (1991)。Pascal を使用した中級プログラミングの原則とテクニックベルモント: ウエスト パブ。出版社ISBN 978-0-314-66314-6
  28. ^ たとえば、Koletzke、Peter (2000) を参照。Oracle Developerの高度なフォームとレポートバークレー: オズボーン/マグロウヒル。ISBN 978-0-07-212048-665ページ。
  29. ^ “最悪の実践 - 悪いコメント” . 2007 年 7 月 24 日に取得
  30. ^ モレリ、ラルフ (2006)。Java、Java、Java: オブジェクト指向の問題解決プレンティス・ホール大学。ISBN 978-0-13-147434-5
  31. ^ ab "Javadoc ツールのドキュメント コメントの書き方" . 2007 年 7 月 24 日に取得Javadoc ガイドラインでは、コメントがプラットフォームにとって重要であると指定されています。さらに、適切な詳細レベルはかなり明確に定義されています。「私たちは、一般的なプログラミング用語を定義したり、概念的な概要を書いたり、開発者向けの例を含めたりするのではなく、境界条件、引数の範囲、およびコーナーケースを指定することに重点を置いて時間と労力を費やしています。」
  32. ^ エドワード・ユアドン (2007). プログラムの構造と設計のテクニックミシガン大学。013901702X。コメントが存在しないとコードの理解が難しくなる可能性がありますが、コメントが時代遅れ、冗長、不正確である場合、またはその他の理由でソース コードの意図された目的を理解することがさらに困難になる場合、コメントは有害となる可能性があります。
  33. ^ デューハースト、スティーブン C (2002)。C++ の落とし穴: コーディングと設計における一般的な問題を回避するアディソン・ウェスリー・プロフェッショナル。ISBN 978-0-321-12518-7
  34. ^ 「コーディングスタイル」。2007 年 8 月 8 日にオリジナルからアーカイブされました2007 年 7 月 24 日に取得
  35. ^ 「アレン・ホルブ」. 2007 年 7 月 20 日にオリジナルからアーカイブされました2007 年 7 月 24 日に取得
  36. ^ アレン・ホルブ、足を撃ち抜くのに十分なロープISBN 0-07-029689-8、1995、マグロウヒル 
  37. ^ ケン・トンプソン。「B へのユーザーの参照」2017 年 7 月 21 日に取得
  38. ^ 「PEP 0350 – コードタグ」、Python ソフトウェア財団
  39. ^ 「コーディングの前後およびコーディング中に何も忘れない」、「コードタグ」コメントを生産的な残りとして使用する
  40. ^ 「タスク リストの使用」、msdn.microsoft.com
  41. ^ "running-config にコメントを残す". Cisco Learning Network (ディスカッション フォーラム)
  42. ^ 「コンフィギュレーション ファイルの管理コンフィギュレーション ガイド、Cisco IOS XE リリース 3S (ASR 900 シリーズ)」。
  43. ^ 「読み書き可能なプログラミング」. haskell.org
  44. ^ "Lua 1.3 でのプログラミング". www.Lua.org 2017-11-08に取得
  45. ^ マクロ.extractDocCommentsAndRunnables
  46. ^ キャスリーン・ジェンセン、ニクラス・ヴィルト (1985)。Pascal ユーザーマニュアルとレポートスプリンガー・フェルラーク。ISBN 0-387-96048-1
  47. ^ ニクラス・ヴィルト (1983)。Modula-2 でのプログラミングスプリンガー・フェルラーク。ISBN 0-387-15078-1
  48. ^ *マルティン・ライザー、ニクラス・ヴィルト (1992)。Oberon でのプログラミングアディソン・ウェスリー。ISBN 0-201-56543-9
  49. ^ "perlpod – Plain Old Documentation フォーマット" . 2011 年 9 月 12 日に取得
  50. ^ "Pod::ParseUtils – POD の解析と変換のためのヘルパー" . 2011 年 9 月 12 日に取得
  51. ^ ab "Perl 6 ドキュメント – 構文 (コメント)" . 2017 年 4 月 6 日に取得
  52. ^ ab 「Python 3 の基本構文」. 2021年8月19日のオリジナルからアーカイブ2019 年2 月 25 日に取得三重引用符は、複数行にまたがることを除き、通常の文字列として扱われます。通常の文字列とは、変数に割り当てられていない場合、コードが実行されるとすぐにガベージ コレクションが行われることを意味します。したがって、#a コメントと同じようにインタプリタによって無視されることはありません。
  53. ^ 「Python のヒント: 複数行の文字列を複数行のコメントとして使用できます」、2011 年 9 月 11 日、Guido van Rossum
  54. ^ タルメージ、ロナルド R. (1999)。Microsoft SQL Server 7. Prima Publishing。ISBN 978-0-7615-1389-6
  55. ^ 「MySQL 8.0 リファレンス マニュアル」. オラクル株式会社 2020 年1 月 2 日に取得
  56. ^ "SQLite によって理解される SQL". SQLite コンソーシアム2020 年1 月 2 日に取得
  57. ^ 「PostgreSQL 10.11 ドキュメント」。PostgreSQL グローバル開発グループ2020 年1 月 2 日に取得
  58. ^ 「Oracle® データベース SQL リファレンス」。オラクル株式会社 2020 年1 月 2 日に取得
  59. ^ アンドレス、マンディ (2003). 生き残るセキュリティ: 人材、プロセス、テクノロジーを統合する方法CRCプレス。ISBN 978-0-8493-2042-2

参考文献

  • Movshovitz-Attias、Dana および Cohen、William W. (2013) プログラミング コメントを予測するための自然言語モデル。計算言語学協会 (ACL)、2013 年。

外部リンク

  • コメントの書き方(デニス・クルコフスキー)
  • PTLogica によるライブ ユーザー マニュアルとしてのソース コード ドキュメント
  • Javadoc ツールのコメントの書き方
「https://en.wikipedia.org/w/index.php?title=Comment_(computer_programming)&oldid=1195319127#Comment_out」から取得