個人にもチームプロジェクトにも役立つソースコードのコメントの使い方

Post on:2012年5月22日

長期に渡るプロジェクトほどコードのコメントは重要性を増すものです。複数のプロジェクトを同時進行したり、複数の人が関わるチームで開発するときなどに役立つコメントの使い方を紹介します。

サイトのキャプチャ

Source Code Comment Styling: Tips and Best Practices

[ad#ad-2]

下記は気になった箇所をピックアップして意訳したものです。

コメントのスタイル

1. インラインのコメント

ほとんど全てのプログラム言語でインラインのコメントが使えます。これは一つのポイントに一行のコメントのテキストを書くことに限定されます。
例を見てみましょう。

    // begin variable listing  
    var myvar = 1;  
    ..

これはその機能を説明するためのコメントで、使い方としては申し分ないでしょう。もしこのようなパラメータがたくさんあるのであれば、インラインのコメントをたくさん使用するのもよいでしょう。しかし、よりシンプルにするのであれば、下記のようにするとより分かりやすくなります。

    if(callAjax($params)) { // successfully run callAjax with user parameters  
     ... code  
    }

無駄な行を増やさないだけでなく、量が増えてもどの箇所へのコメントかが明確に分かります。

2. ブロックのコメント

長い説明が必要な場合は一行のコメントではなく、ブロックで書くとよいでしょう。

    /** 
      * @desc opens a modal window to display a message 
      * @param string $msg - the message to be displayed 
      * @return bool - success or failure 
    */  
    function modalPopup($msg) {  
    ...  
    }

コメントをブロックで書く際、フォーマットを決めておくとよいです。上の例では@をシンボルにし、それぞれの機能をコメントしたものです。
コメントはひと目で重要な情報がチェックできるようにしてください。

[ad#ad-2]

より良いコメントにする4つのテクニック

コードにコメントを使用する際、より容易に分かりやすく、クリーンで系統的にするためのテクニックを紹介します。

1. コメントは分かりやすく

コメントを書く際、しばしばコメントは読むものであるということを忘れてしまうことがあります。コメントは後々、自分を含め他人が読むことを意識して書いてください。

    function getTheMail() {  
        // code here will build e-mail  
      
        /* run code if our custom sendMyMail() function call returns true 
           find sendMyMail() in /libs/mailer.class.php 
           we check if the user fills in all fields and message is sent! */  
        if(sendMyMail()) { return true; // keep true and display onscreen success  
        }  
    }

コメントは多少分かりにくくても何もないよりはましですが、分かりやすいコメントは将来きっと役立つでしょう。

分かりやすいコメントを書くには、書く前に中断して、反映するために少し時間をおいてみてください。コードのどこが紛らわしいか、なぜそのようなコードになったかを考えてみる時間です。

2. スペースで読みやすく

スペースを使用することで、コメントをコードと切り離して読みやすくできます。コードの重要な箇所を一目で読むことができたなら、素晴らしくないですか？

    $dir1 = "/home/";                 // set main home directory  
    $myCurrentDir = getCurDirr();     // set the current user directory  
    $userVar = $get_username();       // current user's username

上記の例ではコメントの前にスペースを入れ揃えています。コードとコメントが分離され、読みやすくなっていると思います。

インラインのコメントは一つ一つのコードには優れていますが、ロジックなどにはブロックでのコメントを勧めます。

$(document).ready(function() {  
        $('.sub').hide(); // hide sub-navigation on pageload  
  
        /** check for a click event on an anchor inside .itm div 
            prevent the default link action so the page doesn't change on click 
            access the parent element of .itm followed by the next .sub list to toggle open/close 
        **/   
  
        $('.itm a').live('click', function(e){ 
        e.preventDefault(); 
        $(this).parent().next('.sub').slideToggle('fast');  
       });  
});

これはスライドするナビゲーション用のjQueryのコードで、l.2のインラインでなぜ「.sub」を隠すのか、ブロックでクリックイベントの処理について記述されたものです。
コメントをブロックで使用する場合も字下げされていると分かりやすいです。

3. コードを書いている間にコメントを

これはスペースを使うことともに、良い習慣と言ってよいでしょう。誰しも作業の終了後にもう一度コードに目を通して、コメントを書くことを望みません。

コメントを書く最も良いタイミングはコードを書いている時で、最も適切なコメントを書くことができるでしょう。さらに、これを習慣化することで、業務に効率化を与えます。作業の終了後にコードに戻ってコメントを書くより必要な時間はずっと少ないはずです。
適切なコメントを残すことで、未来のあなた自身とチームのメンバーの両方が感謝するでしょう。

4. 中断時のコメント

通常、コードをずっと書き続けているわけにはいきません。作業の途中で席をたったり、その日の作業が終了したり、とコードから離れるときがあります。こういった時のために、コードがどこで中断したかをコメントするようにします。

これには2つの理由があります。一つ目は、再開する時すぐにその箇所の内容を理解することができます。二つ目は、ウェブサイトの本番用とテスト用を区別することができます。
コメントを書くポイントは、正確にそれがすることではなく、何をしているかを説明するために使用するとよいでしょう。

sponsors

top of page

©2024 coliss