2010年9月6日月曜日

Perl best practices[Perlベストプラクティス] ７章　ドキュメント


このエントリーをはてなブックマークに追加


ディレクティブ≒コマンド　C言語の#includeや#defineもディレクティブ


ユーザドキュメントと、テクニカルドキュメントを区別する



  • ユーザドキュメント

    • エンドユーザ向け

    • ユーザはperldocを使って説明を読むだろう

    • だからドキュメントはコードのPODのパブリックセクション(=head1,=head2,=over,=item,=backセクション)に書く



  • テクニカルドキュメント

    • 開発者、保守担当向け

    • PODも読むが、ソースコードを読む時間のほうが長いだろう

    • だからドキュメントは非パブリックセクションに追いやる





また、内容を区別すること。


PODテンプレートを用いる


まったくの白紙状態からドキュメントを書くのは、心理的にかなりキツい。
テンプレを用意して、それを埋める作業にすることで、モチベを維持する。

Emacsでの設定は、



;;load an application template in a new unattached buffer...
(defun applivation-template-pi ()
"Inserts the standard Perl application template"  ; For help and info.
(interactive "*")
(switch-to-buffer "application-template-pl"))
;; Set to a specific key combination...
(global-set-key "\C-ca" 'application-template-pl)



拡張テンプレート


前述テンプレートは最小限のものであり、場合により、拡張する。
たとえば、よくある質問と回答履歴とか。


ユーザドキュメントはソースファイルに添付する


ドキュメントを別に管理するのは面倒


近接性



  • ドキュメントは1ヶ所にまとめること。

    • 対応するコードに書くと、コードを汚すことになる。

    • なぜか対応するコードの近くにあるコメント（ドキュメント）は、更新されない傾向があるらしい。





PODはファイルの最後に記述する



  • コードを読もうとして、先頭に数百行のドキュメントがあるとゲンナリする。

  • __END__ラベルのあとに配置して、コンパイル時に調査されないようにする。

  • __DATA__セクションを使用する場合は、ドキュメントを=pod/=cutで囲み、__DATA__ラベルの直前に配置する。



テクニカルドキュメントは適切に再分割する


構成ごとに別々の.podファイルまたはテキストドキュメントを使用する。
構成例は以下。



  • テクニカルドキュメント構成

    • 外部資料

    • 設計書

    • データディクショナリ

    • アルゴリズムの概要

    • 変更ログ





ユーザドキュメントの「See Also(参照)」セクションでこれらのファイルの存在を明記すること。
内部資料、実装の説明、保守に関する注意事項などは、以降の節で説明する。


コメント



  • チームに適したコメントテンプレートを作成する。

  • サブルーチンやメソッドの内部資料を作成するために、箇条書きできるテンプレを用意すること。

    • 一貫性のあるコメントは読み易いし、ここでも「空白を埋めるだけ」効果で心理的なしきい値が低くなる。





アルゴリズムのドキュメント



  • アルゴリズムのドキュメントは、ソースコード内の一行コメントとして、インラインコメントする。


※これはソースの上にかく(次節の「補足用ドキュメントはソースと同じ行の行末に添える」)



# 元の配列をキャッシュする
$raw .= $var_name;



  • それらをつなげて読めばアルゴリズムが推測できるようになるのが理想。

  • コメントが1行で収まらない場合は、コードを見直す必要がある。



補足のためのドキュメント


コードは読めばわかるように書いてあるはずなので、そのヒントとなるドキュメントは必要ないが、専門用語が含まれている場合などは補足しておく必要がある。
この場合は、ソース行末に続けてインラインコメントを書く。



my $QFETM_func_ref; # 量子電界効果伝導モード関数を格納する



コメントがソース行末に収まらない場合は、「表にでない」PODを使用する。後の節で説明。


防御的ドキュメント



  • 迷ったものにはコメントをつける。

  • 未来の自分も、他人も後から苦労するのが目にみえている。

    • 例えば組み込み関数octは引数を8進数にした結果を返すのではなく、実際は、8進数を10進数に変換する。

    • マニュアルで調べなければいけないもの、構文や意味を理解するのに5秒以上かかるものにはインラインコメントをつける。





@option = map +{ $_ => 1}, @flags; # マップブロックではなく
# ハッシュコンストラクタ



コメントを書くよりもコードを書き直すべきか考える



  • コードにコメントを残す必要がある場合は「少なからず」コードを変更する必要性があることを意味する。


先ほどのmapを変更すると以下のようになる。



@options = map { {$_ => 1} } @flags; #ハッシュ参照を返すマップブロック



この例はコメントは要らないかもしれないが、書く場合は事実を端的に書く。


長いテクニカルドキュメントは「表にでない」PODセクションを使用する


　ソースコード内に長い内部資料を埋め込むには、=forと=begin/endを使う。
　以下、=forと=begin/endの違いと使い分け



  • 共通項目

    • コンパイル時に無視され、PODフォーマッタに処理されても目に見える出力がされない。

    • =cutを指定する必要がある。

      • コンパイラをドキュメントスキップモードからPerlコードコンパイルモードに戻すため。



    • フォーマット名を指定する。例えば=for html,=for groffなど。

      • フォーマット名がPOD標準の名前でない場合は、作成した文書がソースコード以外から参照できなくなるかもしれないが、あえてそうする場合は、フォーマット名の頭を大文字にして、最後に：を付ける。これは、設計や実装が特殊であることを示す特殊な目印になる。



    • 表にでないテクニカルドキュメントはできるだけコードの近くに配置する。

    • 内部で使用するものであり、PODフォーマッタの対象ではないので、PODマークアップを使用しない。




  • =for形式を使用する場合

    • 基本的に=for形式を使う。

    • 1段落で収める

    • =forは最後に空行が終了条件である点だけが=begin/endと異なる。




  • =begin/end形式を使用する場合

    • 複数段落

    • サンプルコードの埋め込みが必要





ドキュメントを見直す



  • ユーザや保守担当者との意志疎通として書かれるドキュメントは、あいまいであってはならない。

  • ドキュメントを見直す場合は、書き上げたPODを読み返すのではなく、レンダリングされたものを読む

    • PODをperldocを使用してテキストで読む

    • pod2htmlでHTMLで変換

    • pod2latexで変換




適切な表示ツールを使って最後まで読むのがいい。



  • コードを良く知らない人にチェックしてもらう。





投稿者 時刻:
ラベル: ,

0 件のコメント:

コメントを投稿

登録: コメントの投稿 (Atom)