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

ウィキペディアから、無料の百科事典
ナビゲーションにジャンプ 検索にジャンプ
プロローグコメントが示されインラインコメントが緑で示されている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番目の変数が薄暗くなりました。
サーバーの動作の問題に関するドキュメントはあり
ません。そのため、コーディングするだけです。vtx  = サーバーmappath 「ローカル設定」

アルゴリズムの説明

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

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

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

リソースの包含

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

次のコードは、のためのプロセスフロー描いた、単純なASCII図であるシステム管理に含まれるスクリプトWindowsスクリプトファイルの下で実行されているWindowsスクリプトホストを。コードをマークするセクションはコメントとして表示されますが、図自体は実際にはXML CDATAセクションに表示されます。これは技術的にはコメントとは異なると見なされますが、同様の目的を果たすことができます。[13]

<!-開始: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、このプログラムファイルのソフトウェアライセンスの名前など。

プログラムのあるセクションのアルゴリズムが本または他の参照の説明に基づいている場合、コメントを使用して、本のページ番号とタイトル、またはRequest forCommentsまたは他の参照を与えることができます

デバッグ

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

除外目的でコードをコメントアウトする例を以下に示します。

上記のコードフラグメントは、プログラマーが何らかの理由でデバッグオプションを無効にすることを選択したことを示しています。

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

自動ドキュメント生成

プログラミングツールは、ドキュメントとメタデータをコメントに保存することがあります。[14]これらには、自動ヘッダーファイルインクルードの挿入位置、ファイルの構文強調表示モードを設定するコマンド[15]、またはファイルのリビジョン番号が含まれる場合があります[16]これらの機能制御コメントは、一般に注釈とも呼ばれます。ドキュメントをソースコードコメント内に保持することは、ドキュメントプロセスを簡素化するだけでなく、コードの変更によってドキュメントが最新の状態に保たれる可能性を高める1つの方法と見なされます。[17]

ドキュメンテーションジェネレータの例としては、プログラムを含めるのJavadocで使用するためのJavaDdocのためのDDoxygenのためのCC ++、Javaの、IDLビジュアルエキスパートのためのPL / SQLTransact-SQLのPowerBuilderのはPHPDocのためのPHPをdocstringの形式はPythonLispElixir、およびClojureでサポートされています。[18]

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

構文拡張

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

ディレクティブの使用

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

通訳を指示するこの2つの例は次のとおりです。

  • Unixの「シバン」– #!–使用するインタプリタを指すためにスクリプトの最初の行で使用されます。
  • ソースファイルが使用しているエンコーディングを識別する「魔法のコメント」[21]、たとえばPythonのPEP263。[22]

以下のUnixライクなシステムのスクリプトは、次の両方の使用法を示しています。

#!/ usr / bin / env python3 
#-*-コーディング:UTF-8-*- 
print "Testing" 

やや似ているのは、Cでコメントを使用して、caseステートメントのデフォルトの「フォールスルー」が意図的に行われたことをコンパイラーに通知することです

スイッチ コマンド {
    ケース CMD_SHOW_HELP_AND_EXIT 
      do_show_help (); 
      / *フォールスルー* / 
    case  CMD_EXIT 
      do_exit (); 
      休憩; 
    ケース CMD_OTHER 
      do_other (); 
      休憩; 
    / * ...など... * / 
  }

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

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

#vim:tabstop = 8 expandtab shiftwidth = 4 softtabstop = 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は、コメント内のテキストの配置と視覚的な外観を自動化できるソースコードエディタを持たないプログラマーの間では嫌われる可能性があります。

ソフトウェアコンサルタント兼テクノロジーコメンテーターのAllenHolub [35]は、コメントの左端を揃えることを提唱する専門家の1人です。[36]

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

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

行コメント

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

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

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

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

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

言語が行コメントとブロックコメントの両方を許可する場合、プログラミングチームは、それらを異なる方法で使用する規則を決定できます。たとえば、マイナーコメントに対してのみ行コメントを使用し、高レベルの抽象化を説明するためにコメントをブロックします。

タグ

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

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

  • バグ–修正が必要な既知のバグ
  • FIXME –修正する必要があります。
  • HACK –回避策。
  • TODO –やるべきこと。
  • UNDONE –前のコードの取り消しまたは「ロールバック」。
  • XXX –問題のあるコードや誤解を招くコードについて他のプログラマーに警告する

比較

コメントを指定するための表記規則は大きく異なります。さらに、個々のプログラミング言語は、固有のバリアントを提供する場合があります。詳細なレビューについては、プログラミング言語の比較記事を参照してください。

エイダ

エイダプログラミング言語の使用は「 - 」行の最後にコメントを示します。

例えば:

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

APL

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

例えば:

⍝今の番号を追加します。
C A + B  ⍝追加

( "左")および( "右")プリミティブを持つ方言では、コメントは、無視された文字列の形式で、ステートメントの内部または個別にあることがよくあります。

D 2 × C  '  C A +  '結合'  B

AppleScript

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

(*
このプログラムを表示挨拶。
*)
 挨拶myGreeting 
     表示ダイアログ myGreeting   "世界!" 
終了 挨拶

-あいさつを表示
する「こんにちは」

ベーシック

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

10 REMこのBASICプログラムは、PRINTおよびGOTOステートメントの使用法を示しています。15 REMそれは、フレーズ"HELLO"で画面を埋める20 PRINT "HELLO" 30 GOTO 20 
 
  
  

以降では、マイクロソフトなどの基礎、クイック基本QベーシックVisual BasicのVisual Basic .NETの、およびVBスクリプトまた、FreeBASICGambasなどの子孫では、 '(アポストロフィ)文字の後の行のテキストもコメントとして扱われます。

Visual Basic .NETの例:

パブリック・ クラス Form1の
    プライベート サブ のButton1 Click 送信者 として オブジェクト E のよう にEventArgsは ハンドル Button1をクリック
        'ユーザー
        がプログラムのウィンドウでボタンをクリックすると、
        次のコードが実行されます。remコメントはまだ存在します。

        MessageBox ショー「こんにちは、世界」 「挨拶でポップアップウィンドウを表示
    終了 サブ
エンド クラス

C

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

 / * 
  *プロセスの最大制限を超えているかどうかを確認しますが、
  *ルートを除外してください。これは、ログインと
  *友達がユーザーごとのプロセス制限を
  * rootが実行しているプロセスの量よりも
低い値に設定できるようにするために必要です。 -のRik   * /
 場合 atomic_read P - >ユーザ- >工程 > =  P - > RLIM [ RLIMIT_NPROC 。】rlim_curが
     &&  できるCAP_SYS_ADMIN  &&  できるCAP_SYS_RESOURCE ))
     goto  bad_fork_free ;

C99以降、C ++の//構文を使用することも可能になり、1行のコメントを示しています。

CiscoIOSおよびIOS-XEの設定

感嘆符)Ciscoルータのコンフィギュレーションモードでマークコメントに使用することができる、しかし、そのようなコメントがされていないに保存された不揮発性メモリ(スタートアップコンフィギュレーションを含む)、また彼らは「ショーの実行」コマンドで表示されます。[41] [42]

実際には設定の一部であり、次の方法でNVRAMstartup -configに保存できる人間が読めるコンテンツを挿入することができます

  • インターフェイスまたはBGPネイバーの設定に説明を追加するために使用される「description」コマンド
  • 静的ルートにコメントを追加するための「name」パラメーター
  • アクセスリストの「remark」コマンド
トラフィックを手動で再ルーティングするには、以下のテキストを貼り付けてください
config t
int gi0 / 2
閉じない
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
シャット
出口

ColdFusion

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

 <!---これは「HelloWorld」をブラウザに出力します。---> 
 <CFOUTPUT> 
   Hello Worldの< BR  /> 
 </ CFOUTPUT>

Fortran IV

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

C 
'C'(第一又は'コメント'欄に)されたコメントから始まるC線
C 
WRITE 6 610   610 FORMAT 12 H 、HELLO WORLD END       
   
      

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

Fortran 90

このFortranコードフラグメントは、コメントがその言語でどのように使用されるかを示し、コメント自体が基本的なフォーマット規則を説明しています。

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

Haskell

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

{-これは
より多くの行への
コメントです-} -そしてこれは1行へのコメントです
putStrLn  "Wikipedia"   -これは別のコメントです

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

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

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

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

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

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

後で

%LaTeXのソースファイル\動詞|実際のn | 関数呼び出しは$ nを計算します!$ if $ n \ ge 0 $、ここに定義があります:\\ \ begin { code } fact :: Integer- > Integer fact 0 = 1 fact n + 1 = n + 1 * fact n \ end {コード}
ここで使用してより多くの説明 

    
   
      
\ LaTeX {}マークアップ

Java

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

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

JavaScript

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

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

Lua

Luaのプログラミング言語は、二重ハイフンを使用しています--と同様に単一行コメントのために、エイダエッフェルハスケルSQLおよびVHDL言語。Luaにはブロックコメントもあります。これはで始まり--[[、終了するまで実行されます]]

例えば:

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

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

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

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

--- [[ 
print 10 
-]] 
-> 10

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

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

MATLAB

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

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

%{ 
  %{ 
    (ネストされたコメントの例、インデントは化粧品用です(無視されます)。)
  %}
  テイラーの公式従っシーケンス形成ます       
  ことを私たちは操作する上でのベクトル      
%}
SEQ = D * X - C 。^ N ./ 階乗N ))       

%テイラー近似を取得するために合計します
=合計seq   

ニム

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

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

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

type  Kitten  =  object   ##タイプ
  ageのドキュメント int   ##フィールドのドキュメント

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

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

OCaml

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

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

パスカル

Niklaus Wirthのパスカル言語族(Modula-2Oberonを含む)では、コメントは「(*」で始まり、「*)」で終わります。

例えば:

(*テスト対角線*)
columnDifference  :=  testColumn  -  column ; 
if  row  +  columnDifference  =  testRow  または
    ......。

パスカルの現代方言では、代わりに「{」と「}」が使用されます。[46]

Perl

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

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

Instead of a regular block commenting construct, Perl uses Plain Old Documentation, a markup language for literate programming,[47] for instance:[48]

=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 ; 
    私の $ class  =  ref $ this  ||  $ this ; 
    私の %params  =  @_ ; 
    私の $ self  =  { %params }; 
    $ self $ classを祝福し ます; $ self- >初期化(); $ selfを返します; } 
    
     

R

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

#これはコメント
プリントです「これはコメントではありません」  #これは別のコメントです

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

これらは、ハッシュ文字で始まり、バッククォート、いくつかの開始括弧文字、そして一致する終了括弧文字で終わります。[49]コンテンツは複数行にまたがるだけでなく、インラインで埋め込むこともできます。

# `{{"このバージョンのコメントアウト " 
toggle-case(Str:D $ s)

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

  私のStr $ toggled-文字列= toggle-case( "mY NAME IS mICHAEL!");

}}

サブ トグルケースStr:D  $ s# `(このバージョンのparensが現在使用されています) {
    ..。
}

PHP

PHPのコメントは、C ++スタイル(インラインとブロックの両方)にすることも、ハッシュを使用することもできます。 PHPDocは、Javadocを応用したスタイルであり、PHPコードを文書化するための一般的な標準です。

PowerShell

WindowsPowerShellのコメント

#1行コメント
Write-Host  "Hello、World!"

<#複数

   コメント#>

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

Python

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

#このプログラムは「HelloWorld」をスクリーン
印刷に出力します「HelloWorld!」  #新しい構文に注意してください

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

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

class  MyClass 
    "" "クラスのdocstring" ""

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

def  my_function ():
    "" "関数のdocstring" ""

ルビー

Rubyでのコメント

1行のコメント:(行はハッシュ「#」で始まります)

プット 「これはコメントではありません」

#これはコメントです

プット 「これはコメントではありません」

複数行のコメント:(コメントはキーワード「begin」と「end」の間にあります)

プット 「これはコメントではありません」

=開始

これらの行にあるものは何でも

人間の読者のためだけです

=終了

プット 「これはコメントではありません」

SQL

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

-これは、単一の行コメントである
第二の線に続く- 
SELECT  COUNT * 
       FROM 著者
       著者名前= 'スミス' ; -注:「smith」のみが必要です-このコメントはSQLコードの後に​​表示されます    
                                     

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

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

スウィフト

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

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

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

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

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

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

XML(またはHTML)

XML(またはHTML)の コメントは

<!-

ターミネーターまで数行に広がる可能性があります。

->

例えば、

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

For compatibility with SGML, the string "--" (double-hyphen) is not allowed inside comments.

Security issues

In interpreted languages the comments are viewable to the end user of the program. In some cases, such as sections of code that are "commented out", this may present a security vulnerability.[57]

See also

脚注と参考文献

  1. ^ ソースコードはプログラムコード(機械で翻訳可能な命令で構成されています)に分割できますおよびコメント(プログラムコードをサポートする人間が読める形式のメモやその他の種類の注釈を含む)。ペニーグラブ、アームストロングタカン(2003)。ソフトウェアメンテナンス:概念と実践世界科学。pp。7、plese start120–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. ^ Dixit、JB(2003)。Cでのコンピュータの基礎とプログラミングLaxmiPublications。ISBN 978-81-7008-882-0.
  4. ^ Higham, Desmond (2005). MATLAB Guide. SIAM. ISBN 978-0-89871-578-1.
  5. ^ Vermeulen, Al (2000). The Elements of Java Style. Cambridge University Press. ISBN 978-0-521-77768-1.
  6. ^ a b c "Using the right comment in Java". 2000-03-04. Retrieved 2007-07-24.
  7. ^ W. R., Dietrich (2003). Applied Pattern Recognition: Algorithms and Implementation in C++. Springer. ISBN 978-3-528-35558-6. offers viewpoints on proper use of comments in source code. p. 66.
  8. ^ a b Keyes、Jessica(2003)。ソフトウェア工学ハンドブックCRCプレス。ISBN 978-0-8493-1479-7コメントと「ドキュメンテーションの科学」p。256。
  9. ^ a b c プログラミングスタイルの要素カーニハンプラウガー
  10. ^ a b コードコンプリートマコーネル
  11. ^ Spinellis、Diomidis(2003)。コードの読み取り:オープンソースの観点アディソン-ウェスリー。ISBN 978-0-201-79940-8
  12. ^ 「CodePlotter1.6–この「Visioのような」ツールを使用してコードに図を追加および編集します」2007-07-14にオリジナルからアーカイブされまし2007年7月24日取得
  13. ^ a b Niederst、Jennifer(2006)。一言で言えばWebデザイン:デスクトップクイックリファレンスオライリー。ISBN 978-0-596-00987-8「コメント」とプログラミングまたはマークアップ言語の他の構文要素との違いは、微妙なニュアンスを伴う場合があります。Niederstは、そのような状況の1つを次のように述べています。「残念ながら、XMLソフトウェアはコメントを重要でない情報と見なし、処理する前にドキュメントからコメントを削除するだけです。この問題を回避するには、代わりにXMLCDATAセクションを使用してください。」
  14. ^ たとえば、 Wynne-Powell、Rod(2008)を参照してください写真家のためのMacOs X:Macユーザー向けに最適化された画像ワークフローオックスフォード:フォーカルプレス。ISBN 978-0-240-52027-8 243ページ
  15. ^ ラム、リンダ(1998)。VIエディターの学習セバストポル:オライリー&アソシエイツ。ISBN 978-1-56592-426-0 Vim構成ファイルでのモードライン構文の使用について説明します。
  16. ^ たとえば、 Berlin、Daniel(2006)を参照してください実用的な転覆、第2版バークレー:APress。ISBN 978-1-59059-753-8 168ページ。
  17. ^ アンブラー、スコット(2004)。オブジェクト入門書:UML2.0を使用したアジャイルモデル駆動型開発ケンブリッジ大学出版局。ISBN 978-1-397-80521-8
  18. ^ Clojureでのdocstringを使用した関数定義
  19. ^ ムラフ。C#2005NS。56。
  20. ^ c2:HotComments
  21. ^ 「クラスエンコーディング」ルビーruby-lang.org 2018年12月5日取得
  22. ^ 「PEP263–Pythonソースコードエンコーディングの定義」Python.org 2018年12月5日取得
  23. ^ Polacek、Marek(2017-03-10)。"-Wimplicit-GCC7でのフォールスルー"RedHat開発者RedHat 2019年2月10日取得
  24. ^ 「Microsoftプログラマーは初期のソフトウェアコードで冒とく的な表現を隠した」、Lisa Eadicicco、2014年3月27日、businessinsider.com.au
  25. ^ (たとえば、 Linux Swear Countを参照)。
  26. ^ Goodliffe、Pete(2006)。コードクラフトサンフランシスコ:ノースターチプレス。ISBN 978-1-59327-119-0
  27. ^ Smith、T。(1991)。Pascalを使用した中間プログラミングの原則と手法ベルモント:ウェストパブ。株式会社ISBN 978-0-314-66314-6
  28. ^ たとえば、 Koletzke、Peter(2000)を参照してくださいOracle Developer Advanced Forms&Reportsバークレー:オズボーン/マグロウヒル。ISBN 978-0-07-212048-6 65ページ。
  29. ^ 「最悪の慣行-悪いコメント」2007年7月24日取得
  30. ^ モレリ、ラルフ(2006)。Java、Java、Java:オブジェクト指向の問題解決プレンティスホールカレッジ。ISBN 978-0-13-147434-5
  31. ^ a b "Javadocツールのドキュメントコメントの書き方" 2007年7月24日取得Javadocガイドラインでは、コメントがプラットフォームにとって重要であると指定されています。さらに、適切な詳細レベルはかなり明確に定義されています。「一般的なプログラミング用語の定義、概念の概要の記述、開発者向けの例の追加ではなく、境界条件、引数範囲、コーナーケースの指定に時間と労力を費やしています。」
  32. ^ Yourdon、Edward(2007)。プログラムの構造と設計のテクニックミシガン大学。013901702X。コメントが存在しないとコードを理解するのが難しくなる可能性がありますが、コメントが廃止、冗長、不正確である場合、またはソースコードの意図された目的を理解するのがより困難になる場合、コメントは有害になる可能性があります。
  33. ^ Dewhurst、Stephen C(2002)。C ++の落とし穴:コーディングと設計における一般的な問題の回避アディソン-ウェスリープロフェッショナル。ISBN 978-0-321-12518-7
  34. ^ 「コーディングスタイル」2007年8月8日にオリジナルからアーカイブされまし2007年7月24日取得
  35. ^ 「アレンホーラブ」アーカイブされたオリジナルの2007年7月20日に2007年7月24日取得
  36. ^ Allen Holub、足元自分を撃つの十分なロープ ISBN 0-07-029689-8、1995、McGraw-Hill 
  37. ^ ケントンプソン。「ユーザーによるBへの参照」2017721日取得
  38. ^ 「PEP0350–コードタグ」、Python Software Foundation
  39. ^ 「コーディング前、コーディング後、コーディング中は何も忘れない」、「codetag」コメントを生産的な残りとして使用
  40. ^ 「タスクリストの使用」、msdn.microsoft.com
  41. ^ 「running-configにコメントを残してください」Cisco Learning Network(ディスカッションフォーラム)
  42. ^ 「設定ファイルの管理設定ガイド、Cisco IOS XEリリース3S(ASR 900シリーズ)」
  43. ^ 「文芸的プログラミング」haskell.org
  44. ^ 「Lua1.3でのプログラミング」www.Lua.org 2017118日取得
  45. ^ macros.extractDocCommentsAndRunnables
  46. ^ 「コメント」www.freepascal.org 2017920日取得
  47. ^ 「perlpod–プレーンオールドドキュメンテーションフォーマット」20119月12日取得
  48. ^ "Pod :: ParseUtils –PODの解析と変換のヘルパー" 20119月12日取得
  49. ^ a b "Perl 6ドキュメント–構文(コメント)" 2017年4月6日取得
  50. ^ a b "Python3の基本構文" 2019年2月25日取得三重引用符は、複数行にまたがることができることを除いて、通常の文字列として扱われます。通常の文字列とは、変数に割り当てられていない場合、そのコードが実行されるとすぐにガベージコレクションされることを意味します。したがって、#aコメントと同じようにインタプリタによって無視されることはありません。
  51. ^ 「Pythonのヒント:複数行の文字列を複数行のコメントとして使用できます」、2011年9月11日、Guido van Rossum
  52. ^ Talmage、Ronald R.(1999)。Microsoft SQL Server7PrimaPublishing。ISBN 978-0-7615-1389-6
  53. ^ 「MySQL8.0リファレンスマニュアル」オラクル株式会社2020年1月2日取得
  54. ^ 「SQLiteによって理解されるSQL」SQLiteコンソーシアム2020年1月2日取得
  55. ^ 「PostgreSQL10.11ドキュメント」PostgreSQLグローバル開発グループ2020年1月2日取得
  56. ^ 「Oracle®データベースSQLリファレンス」オラクル株式会社2020年1月2日取得
  57. ^ Andress、Mandy(2003)。存続するセキュリティ:人、プロセス、テクノロジーを統合する方法CRCプレス。ISBN 978-0-8493-2042-2

さらに読む

外部リンク