« 「どこかに、逃げ込んでいないか」のコメント | トップページ | 「サーバ台数の見積もり」について »

2006年8月24日 (木)

「文芸的プログラミング」を試みる。

Documentation and source code are written into one source file. Both the complete source code and its documentation can be extracted from this file with specific utilities. The information is written and presented in a reading order suitable for human consumption with detailed explanations. The code is automatically rearranged for ordinary processing by other computer tools, such as compilers or interpreters.
「Literate programming」(Wikipedia)

Donald Knuthが提唱した「文芸的プログラミング」のコンセプト-ソースコードとドキュメントを一つのものとして扱う-は、Java言語のJavaDoc や、Perl言語のPOD などの「埋め込みドキュメント」に受け継がれています。

私は、プログラムの「詳細設計書」のようなもの、つまり、プログラムの呼び出しインターフェイス仕様を書いたり、プログラムの処理を書いたりするドキュメントを、今まで、必要に応じて作成していたのですが、やはり、これは、「ソースコードそのもの」を、そのまま仕様とするようにすべきだと思いました。結局、プログラマは、ドキュメントをソースにコピーするような作業をやりますから、初めからソースファイルに書く方が、無駄がないですよね。

よく、OracleデータベースのPL/SQL言語(ストアド・プロシージャ)を使用して、アプリケーション・ロジックをサーバに置く、ということをやっています。このインターフェイス仕様を書くのに使えるツールはないか、とネットを探し回った結果、PLDoc というソフトウエアを見つけました。

以下のように、日本語も、ちゃんと使えるようになっています。
(ver0.8.3です。ver0.8.3.1では使えなくなってしまってます。)

pldoc -doctitle \"Samples\" -overview overview1.html -d Samples -inputencoding Shift_Jis sample*.sql

エンコードで、"UTF-8"だけでなく、"Shift_Jis"も使えるのは有難いですね。HTMLをUTF-8にするのは良いのですが、ソースコードは、OSネイティブな文字コードを使いたいので。

しばらく、このツールを使って、インターフェイス仕様を書いているのですが、今のところは、順調にいっているようです。「紙にしにくい」というのは、難点かなと思っていますが、プログラマ以外は読まない類のドキュメントですので、問題はなさそうです。

ちなみに、数ある「埋め込みドキュメント」のツールの中では、RDOC(Ruby Documentation System) が秀逸だと思います。ソースコードまで見られるのは、素晴らしいですね。

---

Book 文芸的プログラミング

著者:ドナルド・E. クヌース
販売元:ASCII
Amazon.co.jpで詳細を確認する

|

« 「どこかに、逃げ込んでいないか」のコメント | トップページ | 「サーバ台数の見積もり」について »

コメント

こんばんは。初めまして!
少しずれますが『人月の神話』にある自己文書プログラムにひどく感動して早速実施してみたことがあります。ドキュメント作成で問題になるのはメンテナンスですが、プログラムとドキュメントが同じファイルにあるので改善できていました。
ですが、客先がISO取得のためにドキュメントを規定してしまったので却下。短い改善でした・・・。

投稿: 手文庫 | 2006年8月26日 (土) 01時24分

手文庫さん、はじめまして。
コメント、トラックバックありがとうございます。
>客先がISO取得のためにドキュメントを規定してしまったので却下。
納品ドキュメントを、一律に規定されてしまうと、つらいですね。
プロジェクトごとに、本当に必要な納品物件を考えるべきだと思います。
---
ちなみに、このブログにあります、「詳細設計書」は納品物件ではなく、プロジェクト内部でのコミュニケーションに使います。
詳細設計書の類は、納品物としては必要のないもの、と思います。
客先でメンテできるとは思えませんので。

投稿: ron | 2006年8月27日 (日) 00時37分

はじめまして、
ronさんはPLDocで日本語のコメントを生成できるかとうか確認しましたか。

私は、何回でやってみましたが、全部失敗しました。

投稿: 困った人 | 2008年5月23日 (金) 16時36分

>困った人 さん

>ronさんはPLDocで日本語のコメントを生成できるかとうか確認しましたか。

本文にもありますが、
ver0.8.3 で日本語コメントを生成できることは確認しています。
(Windows・Shift_Jis です)

ver0.8.3.1 ではどうやっても無理でしたね。
海外製のプログラムにありがちですが、バージョンによってできたりできなかったりするようです。

投稿: ron | 2008年5月23日 (金) 23時46分

コメントを書く



(ウェブ上には掲載しません)


コメントは記事投稿者が公開するまで表示されません。



« 「どこかに、逃げ込んでいないか」のコメント | トップページ | 「サーバ台数の見積もり」について »