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

Post on:2012年5月22日

コメントのスタイル

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. コードを書いている間にコメントを

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

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