Perl Hackers Hub

第8回 Perlによる大規模システム開発・設計のツボ(1)

この記事を読むのに必要な時間:およそ 4 分

コメントとドキュメント

コメントやドキュメントも重要なコミュニケーション手段です。

悪いコメント

よく見かける悪いコメントは次のようなものです。

# ここはこんな感じにしておく
# 絶対に変更しないコト!!

上記のように事情や意味がよくわからない文章を書いてはいけません。

# parsed_queryをsetupする
$parsed_query->setup;

上記のように自明なコメントは,コードの一覧性が下がるだけなので必要ありません。

# 終了したのでコメントアウト
# call_some_func(@array_of_arguments);
# TODO : あとで実装する

上記のようにコメントアウトやTODOをメモするのではなく,バージョン管理システムやチケット管理システムを利用して,コード上には現在動いているもののみを残しましょう。

# deprecated : 廃止予定

上記のようにコメントで伝えるのではなく,デバッグ時のエラーメッセージや警告などを利用して伝えましょう。

表明による予防的コーディング

次のようなコメントを目にすることがあります。

# $minは0<= * <= 59の間
my $min = shift;

こういった入力や出力が満たすべき性質についてのコメントは,アサーションなどを利用して書き換えましょう。

my $min = shift;
assert 0 <= $min && $min <=60;

Carp::Assertなどを用いて上記のように記述しておけば,実行時にassert文が検証されバグを追跡しやすくなります。

コードをコメントで分割しない

機能追加や仕様変更が多くなると,次のような関数を見かけます。

sub add_items {
    my ($self,$items) = @_;
    # ここは○○をしている
    :
    # ここは○○をしている
    :
    if( ! *** && ! ***) {
        # ○○の場合
        :
    } else {
        # ○○が出ない場合
        :
    }
}

上記ではコメントの記述で機能を分割しています。このようなコメントを記述するのではなく,意味が明瞭でテストしやすい関数に機能を分割しましょう。

コメントとドキュメントの違い

Perlでは,#によるコメントとpodによるドキュメントをコード上に情報として記述できます。これらは次のように,前提とする読者が違う点を意識しましょう。

  • コメントは,内部実装の理解のために必要な情報
  • ドキュメントは,ライブラリ利用者のために必要な情報

コメントの役割は補助的なものです。できるだけ,コメントは書かなくとも意図が伝わるようにしましょう。コード中の名前付けや関数の粒度を小さくすることをまず考え,それでも意図が伝わりにくい部分についてのみコメントを記述します。

ドキュメントには,主にモジュールの役割や公開メソッドなどのインタフェースの情報を記述します。インタフェースが変更されたら修正する必要があります。

コメントやドキュメントを記述しても,プログラムの動作を保証することはできません。動作を保証するためではなく,コードの読者をサポートする正しい情報を伝えるために,最新の状態を保ちましょう。

著者プロフィール

広木大地(ひろきだいち)

筑波大学大学院卒業後,2008年度に新卒として株式会社ミクシィに入社。

広告システムの開発に従事したのち,システム本部たんぽぽ開発グループに所属。現在は「刺身の上にたんぽぽを乗せる仕事」を撲滅するべく,サービスアーキテクチャの設計/開発や技術者教育などを担当している。

YAPC::Asia 2010にて,mixiのアーキテクチャについての発表を行った。