ソースコードコメントスタイリングのヒントとベストプラクティス

大規模なプロジェクトに時間を費やしてきた開発者は、コードコメントの重要性を理解しています。同じアプリケーションに多数の機能を組み込んでいる場合、事態は複雑になる傾向があります。関数、変数参照、戻り値、パラメータなど、非常に多くのデータビットがあります。?

自分のコードをコメントすることが、ソロプロジェクトでもチームプロジェクトでも不可欠であることは驚くに当たりません。しかし、多くの開発者はこのプロセスの進め方を知らない。私は自分の個人的なトリックのいくつかを概説しました 整然とした、フォーマットされたコードのコメントを作成する. 標準とコメントテンプレートは開発者によって異なります - しかし、最終的にはあなたが努力するべきです きれいで読みやすいコメント コードのわかりにくい部分をさらに説明する.

コメントフォーマットの違いのいくつかを議論し始めるべきです。これにより、プロジェクトコードでどれだけ詳細になることができるかについてのより良いアイデアが得られます。その後、すぐに使い始めることができる具体的なヒントと例をいくつか紹介します。!

コメントスタイル：概要

提示されたこれらの考えは単なるものであることに留意されたい。 ガイドライン よりクリーンなコメントに向けて。個々のプログラミング言語では、ドキュメントの設定方法に関するガイドラインや仕様は定められていません。.

そうは言っても、現代の開発者たちはグループ化して独自のコードコメントシステムをフォーマットしました。いくつかの主流のスタイルを提供し、それらの目的の詳細に入ります.

インラインコメント

事実上すべてのプログラミング言語が提供しています インラインコメント. これらは単一行のコンテンツに限定されており、特定のポイントの後でテキストをコメントするだけです。たとえばC / C ++では、次のようにインラインコメントを始めます。

//変数リストの開始var myvar = 1;… 

これは、数秒間コードを調べて 混乱を招く可能性のある機能について説明する. たくさんのパラメータや関数呼び出しを扱っているのなら、たくさんのインラインコメントを近くに置いてください。しかし最も有益な用途は 小さな機能についての簡単な説明.

if（callAjax（$ params））//ユーザーパラメータを指定してcallAjaxを正常に実行する…code

上記のすべてのコードは、開き括弧の後の新しい行に配置する必要があります。さもなければそれはすべて同じコメント行で捕らえられるでしょう! 船外に出ないで 通常、ページの下に一行コメントを表示する必要はありませんが、特にコード内の混乱を招くジャンクションの場合は、最後の1分間に削除する方がはるかに簡単です。.

記述ブロック

あなたが大きな説明を含める必要があるとき、一般的に単一のライナーはトリックをしません。プログラミングのあらゆる分野で使用されるフォーマット済みのコメントテンプレートがあります。. 記述ブロック 特に関数やライブラリファイルの周りに見られる。新しい機能を設定するときはいつでもそれは良い習慣です。 宣言の上に説明ブロックを追加する.

/ ** * @descはメッセージを表示するためのモーダルウィンドウを開きます* @param string $ msg  - 表示されるメッセージ* @return bool  - 成功または失敗* / function modalPopup（$ msg）… 

上記は、説明関数のコメントの簡単な例です。私はおそらくJavaScriptで呼ばれる関数を書いた modalPopup これは単一のパラメータを取ります。上記のコメントでは、phpDocumentorに似た構文を使用しました。各行の先頭には @ 記号の後に選択されたキーが続きます。これらはあなたのコードには何の影響も及ぼさないので、次のように書くことができます。 @説明 の代わりに @desc 何の変更もなし.

これらの小さな鍵は実際には呼ばれます コメントタグ それはウェブサイト上で詳細に文書化されています。あなた自身のものを作って、あなたがあなたのコードを通して望むようにこれらを使ってください。私は彼らがすべてを流し続けるのを助けるのを見つけます 一目で重要な情報を確認できます. また、私は / * * / ブロックスタイルのコメントフォーマット。これはすべてを保つでしょう ずっときれい 各行の先頭に二重スラッシュを追加するよりも.

グループ/クラスのコメント

関数やループをコメントアウトする以外に、ブロック領域はそれほど頻繁には使用されません。あなたが本当に必要なところ コメントをブロック バックエンド文書やライブラリファイルの先頭にあります。あなたのウェブサイトのすべてのファイルについて万全を期してしっかりとした文書を書くことは簡単です - 私たちはWordPressのような多くのCMSでこの習慣を見ることができます.

あなたのページの一番上の領域にはファイル自体に関するコメントが入っているはずです。このようにしてあなたはすることができます 編集場所をすばやく確認 同時に複数のページで作業するとき。さらに、この領域を次のように使うことができます。 あなたが必要とする最も重要な機能のデータベース クラス外.

/ ** * @descこのクラスはユーザとの対話のための関数を保持します*例にはuser_pass（）、user_username（）、user_age（）、user_regdate（）が含まれます。* @author Jake Rocheleau [email protected] * @required settings.php * /抽象クラスmyWebClass  

あなたは私が偽物のためにほんの小さなサンプルクラスを使ったのを見ることができます myWebClass コード。メタ情報を追加しました 私の名前と連絡先のEメールアドレス. 開発者がオープンソースコードを書いているとき、これは一般的に良い習慣です。これは、大規模な開発チームで作業するときにも確実な方法です。.

タグ @必須 私が他で使用したのを見たことはありません。私はいくつかのプロジェクトでフォーマットに追いついてきましたが、私は多くのメソッドをカスタマイズしたページでのみでした。あなたがファイルにページを含めるときはいつでも、あなたが何らかのコードを出力する前にそれらは来なければなりません。そのため、メインクラスのコメントブロックにこれらの詳細を追加するのは良い方法です。 どのファイルが必要かを覚えておいてください.

フロントエンドコードのコメント

3つの重要なコメントテンプレートについて説明したので、他の例をいくつか見てみましょう。静的HTMLからjQueryおよびCSSコードに移行した多くのフロントエンド開発者がいます。 HTMLコメントはプログラミングアプリケーションと比べてそれほど意図的ではありませんが、スタイルライブラリやページスクリプトを書いているときには、時間が経つにつれて面倒になることがあります。.

JavaScriptは、Java、PHP、およびC / Cに似た、より伝統的なコメント方法に従います。++. CSSはスラッシュとアスタリスクで囲まれたブロックスタイルのコメントのみを利用します。. CSSもJSもサーバーサイドでは解析されないため、コメントは訪問者にはっきりと表示されることに注意してください。.

特にCSSファイルを分割するのは面倒です。私たちは皆、Internet ExplorerやSafariに対する修正を説明するためにインラインコメントを残すことに精通しています。しかし、私はCSSコメントをjQueryとPHPのレベルで使用できると考えています。コードのコメントに関するいくつかの詳細なヒントに触れる前に、スタイルグループの作成について詳しく調べてみましょう。.

CSSスタイルグループ

何年もCSSを設計してきた人々にとって、それはほとんど第二の性質として来ます。あなたはゆっくりとすべてのプロパティ、構文を暗記し、そしてスタイルシートのためにあなた自身のシステムを構築します。自分の仕事を通して私は自分が呼ぶものを創り出しました グルーピング 類似のCSSブロックを1つの領域にペアリングする.

CSSの編集に戻ると、数秒で必要なものを簡単に見つけることができます。スタイルをグループ化する方法は完全にあなた次第です。それがこのシステムの美しさです。以下に概説したいくつかのプリセット標準があります。

• @resets - デフォルトのブラウザの余白、パディング、フォント、色などを削除する.
• @フォント - 段落、見出し、ブロック引用符、リンク、コード
• @ナビゲーション - 主要なウェブサイトのナビゲーションリンク
• @layout - ラッパー、コンテナ、サイドバー
• @headerと@footer - これらはあなたのデザインによって異なります。考えられるスタイルには、リンクと番号なしリスト、フッター列、見出し、サブナビゲーションなどがあります。

スタイルシートをグループ化すると、 タグ付けシステム 大いに役立つことができます。しかし、PHPやJavaScriptとは異なり、私は単一の @グループ タグの後にカテゴリまたはキーワードが続きます。以下に2つの例を含めたので、私の言っていることを実感できます。.

/ ** @group footer * / #footer styles…

/ ** @groupフッター、小さなフォント、列、外部リンク** / 

あるいは、各コメントブロックにもう少し詳細を追加することもできます。私が選ぶ 物事を単純明快に保つ そのため、スタイルシートは読みやすくなっています。あなたがその文章を理解している限り、コメントすることはドキュメンテーションについてのすべてです!

より良いコメントスタイリングのための4つのヒント

この記事の前半では、コードをコメント化するためのさまざまな形式について説明しました。コードをきれいに整理し、理解しやすくするための全体的なヒントを説明しましょう。.

1.すべてを読みやすくする

時には開発者として私たちはそれを忘れる 人間が読むためのコメントを書いています. 私たちが理解しているすべてのプログラミング言語は機械用に構築されているので、プレーンテキストに変換するのは面倒です。大学レベルの研究論文を書くためにここにいるのではないことに注意することは重要ですが、 ヒントを残すだけ!

function getTheMail（）//ここのコードは私達のカスタムsendMyMail（）関数呼び出しがtrueを返す場合にe-mail / * runコードを構築しますfind findMyMail（）を/libs/mailer.class.phpに入れてユーザーがすべてのフィールドに記入したかどうかチェックしますそしてメッセージが送信されます！ * / if（sendMyMail（））trueを返す。 // trueを維持し、画面上に成功を表示します

ほんの数語でさえ 何もないよりマシ. 将来、プロジェクトの編集や作業に戻ると、どれだけ忘れてしまうかが驚くことがよくあります。毎日同じ変数や関数名を見ているわけではないので、コードの大部分はゆっくりと忘れがちです。それであなたはできる コメントを残しすぎない! しかし、あなたはあまりにも多くの悪いコメントを残すことができます.

一般的な経験則として, 書く前に少し時間をかけて振り返る. 自問してみてください プログラムについて最も混乱しているもの そして どのようにあなたはそれを最もよく説明することができますか “ダミー” 言語? また考えなさい あなたが正確に自分のコードを書いている理由.

カスタムビルド（またはサードパーティ）機能の目的を忘れた場合、最もわかりにくいエラーがいくつか表示されます。. コメント証跡を残して他のいくつかのファイルに戻る これにより、機能を覚えやすくなります。.

2.スペースをいくらか軽減する!

私は十分に強調することができない 空白 することができます。これは行きます 二重に真実 何百ものファイルを持つ大規模Webサイトで作業しているPHPおよびRuby開発者のためのものです。あなたは一日中このコードを見つめているでしょう！あなたがただ重要な分野まですくい上げることができればそれは素晴らしいことではないでしょうか?

$ dir1 = "/ home /"; //メインホームディレクトリを設定します。$ myCurrentDir = getCurDirr（）; //現在のユーザディレクトリを設定します$ userVar = $ get_username（）; //現在のユーザーのユーザー名

上の例では、各行のコメントとコードの間に余分なパディングがあることに気付くでしょう。ファイルをスクロールしていると、このスタイルのコメントができます。 はっきりと目立つ. それ エラーを見つけてコードを何百倍も簡単に修正できます。 可変ブロックがそうであるとき クリーン.

あなたはそれがどのように動作するかについて混乱しているところで関数の中のコードに同様のタスクを実行することができます、しかしこの方法は結局インラインコメントであなたのコードを散らわせるでしょう、そしてそれは秩序の正反対です！このシナリオではお勧めします ロジック領域の周りに大きなブロック行コメントを追加する.

$（document）.ready（function（）$（ '。sub'）。hide（）; // pageload / **のサブナビゲーションを隠す.itm div内のアンカーでクリックイベントをチェックするデフォルトリンクを防ぐクリックしてもページが変更されないように.itmの親要素に続けて次の.subリストを開いて、閉じる** / $（ '。itm a'）を切り替えるlive（ 'click'、function（e ）e.preventDefault（）; $（this）.parent（）。next（ '。sub'）。slideToggle（ 'fast'）;）;）;

これは、サブメニューのスライド式ナビゲーションを対象とした、ちょっとしたjQueryコードです。最初のコメントは、私たちがすべての人を隠している理由を説明するためのインラインです。 .サブ クラス。ライブクリックイベントハンドラの上に、ブロックコメントを使用しました。 すべての文章を同じ点に字下げした. これは、実行中の段落よりも物事をきれいにします - 特にあなたのコメントを読んでいる人にとっては.

3.コーディング中のコメント

適切な間隔に沿って、これは入るべき最も良い習慣の1つであるかもしれません。プログラムがうまくいった後にプログラムを見直して、すべての部分を文書化したいと思う人はいません。私たちのほとんどは混乱している分野について戻って文書化することすらしたくありません。それは本当に多くの作業を要します.

コーディング中にコメントを書くことができれば すべてはまだあなたの心に新鮮になります. 通常、開発者は問題に巻き付いて、最も簡単な解決策を探すためにWebを探します。あなたがEurekaの瞬間に当たってそのような問題を解決するとき、あなたがあなたの前のエラーを理解するところで一般に明快さの瞬間があります。これは ベストタイム あなたのコードについてオープンで誠実なコメントを残す.

さらに、これはあなたがあなたのファイルの全てをコメントすることに慣れることに慣れを与えるでしょう。関数を既に構築した後は、戻って何かがどのように機能するかを理解するのに必要な時間ははるかに長くなります。. 将来の自己とチームメイトの両方が、コメントを早めに残してくれてありがとう.

4.バギーエラーへの対処

私たち全員がコードを書くのに何時間もコンピュータの前に座ることはできません。私たちは試すことができると思いますが、ある時点で私たちは眠る必要があります！あなたはたぶんその日のためにあなたのコードでいくつかの機能がまだ壊れていると別れなければならないでしょう。このシナリオでは、それはあなたが重要です あなたが物事を中断した場所についての長く詳細なコメントを残す.

新鮮な夜の睡眠の後でさえも、コーディングのスイングに戻るのがどれほど難しいかに驚くかもしれません。たとえば、画像アップロードページを作成していて、それを未完成のままにしなければならない場合は、 プロセスのどこで中断したかについてコメントする必要があります. 画像はアップロードされ、一時メモリに保存されていますか？または、アップロードフォームで認識されていないか、アップロード後にページに正しく表示されていない可能性があります。.

エラーをコメントすることは、2つの主な理由から重要です。まずはじめに 中断したところから簡単に拾う そして 問題を解決するために、もう一度気にしてやり直してください。. そして第二にあなたがすることができます あなたのウェブサイトのライブプロダクション版とテストの根拠を区別する. コメントは 何をしているのか説明する, 正確には機能しません.

結論

Webアプリケーションおよびソフトウェアの開発は、困難なことではありますが、充実したプラクティスです。あなたが本当にソフトウェアを構築することを理解している数少ない開発者の1人であるならば、それはあなたのコーディング技術で成熟することが重要です. 説明的なコメントを残すことは長期的にはちょうど良い習慣です, 後悔することはないでしょう!

より明確なコードコメントの提案がある場合は、以下のディスカッションエリアにお知らせください。!