ソースコードドキュメントを作るときに気をつけていること
月並みですが、私がdoxygenなどでソースコードにドキュメントを書くとき気をつけていることです。目指しているのは「練習しなくても誰でも速読できる文書を書く」方法です。普通の言葉遣いとは似て非なる、近いのに遠いとっつきにくさがありますが、一度慣れてしまえば案外簡単。
パラグラフにタイトルをつける
まずパラグラフの連続として全体構成を考えます。タイトルは全てのパラグラフに必須ではありませんが、「このタイトルを並べただけで単元(ページ)の流れ・結論が分かるように気をつける」と、だいたいうまく構成できます(*1)。
結論を先にインデックス(*2)
よく「結論を先に」と言います。しかし同じ事を毎回二度作文するのは手間と文字数のムダ。なので最初にパラグラフタイトルをリストすることで代えます。つまりインデックスです。もし内容が一種類だけなら、インデックスも必要なく、ページに大タイトルという名の結論を与えるだけ。
1パラグラフ3行くらいまで
3行とは、「パラグラフタイトル(左上)からパラグラフの終端(右下)まで一瞥してすぐ読めるボリューム」で、文字数はメディアによります。ワイドなWebレイアウトならけっこう長く書けますが、縦置き横書き文書だと短め推奨。長いと読み飛ばされます。
1パラグラフ2転くらいまで
1パラグラフ内の意味を総じても「AだからBですがCもあります」程度までに。もし1パラグラフで「AだからBですがCもあります。またDに注意してください。なぜならFだからです」など反転や発展を詰め込んでいくと読み飛ばされます。パラグラフを分割するか、下記のように図示を使います。
対比や関連は文書ではなく図示
上記のパラグラフ/センテンス制約では、「対比・関係」「本筋とは反するが重要な特記事項」を列挙するのはほぼ不可能です。しかし概念や理論的な説明は、些事を列挙しなければ伝わらない事も多く、この場合、リスト・テーブル・注記など、文体をそぎ落とす代わりに装飾されたブロックを使います。
用字と用語の統一
最後にいわゆる「表記ゆれに気をつけよう」です。ですます統一はもちろん、技術用語の表記・用法はブレると読みにくいです。また漢字の使い方なども、出版編集者ほど気にしなくても良いところですが、「作る」「つくる」「造る」などケースバイで用法統一も少しは気にしたいところです(ただコレが極端に酷い人って、技術系デスクワーカーの界隈ではあまり見たことがないような…)。
まとめ「明確 = 簡潔で一意」
学校の作文や役所の書類ではないので「機能を果たさない表現を避ける」のがポイントです(例えば、リストやテーブルでは、ですますといった必須とは限らない文字数をわずかに省ける)。個人的には以下の点で独特の地平に立つテクニックと意識しています。
目的 | 文語や口語表現 | |
---|---|---|
普通の作文 | ニュアンスや情緒を伝達するもの | 要る |
技術文書 | 構造・概念を明確に伝達するもの | 要らない |
これはドキュメントだけでなく、ソースコード内のコメントについてもあてはまる事が多いと思います。ですますの統一とか余剰な情報やメンテナンスコストを乗せないよう体言止めの多用などをしていると、そもそもコード内コメントに日本語すら必要ないのではないかと思う時もあります。またちょっと逆説的なんですが、このようなミニマムな説明で表現しきれない仕様は、その仕様自体、冗長性が本当に適切か考え直す時があります。
*1:ちなみに私は、パラグラフ分割とタイトル付与の成否が完成度の50%を占めると見ています。仕様が簡潔でまとまっていると、説明も簡潔にするのが簡単です。そうでないものは苦労します。ただ例外的に簡潔な仕様だけど説明しにくいことがあります。関連するクラスや関数などポイントが2箇所以上に分かれて相互に循環する場合です(正しさを説明するのにタライ回しが必要なケース。必要以上の汎用性を削った場合に生じやすいです。ライブラリ層ではあまり生じませんが、アプリケーション層では多く発生します)。こればっかりは、簡単な事なのにベストな説明表現を一意に決定するのが困難。
*2:ただし他の出力ドキュメントの一部に食い込む形だと、目次があるのはちょっと浮く時があるので「タイトルと一行説明&内容を少なめにしてパラグラフ列挙するだけ」などでどうにかコンパクトにして切り抜ける方向で考えたりします(もしそれでおさまりそうもないならやむなく別ページ)。