CRAIDでブリッジエンジニアをしているKakeyaです。現在同じチームで一緒に働いているエンジニアのCrisさんが投稿した記事の翻訳記事になります。
こちらが元記事になりますので是非読んでみてください。
翻訳元記事(オフショア子会社Fullspeed Technologies Inc.の技術ブログ)
多くの開発者がドキュメント作成に前向きになれないのは、価値を感じていないからではありません。コードを改良する方法には慣れているのに対し、良いドキュメントや役立つドキュメントの作り方に慣れていないからです。私たちのチームもこの課題に直面していたため、ドキュメント作成のアプローチのアイデアを探求しました。また、私たちのチームが主にクローズドソースプロジェクトに取り組んでいることも重要なポイントです。
この記事には、限られたプロジェクトでのみ試されたアイデアが紹介されています。これらのプロジェクトではうまく機能しましたが、すべてのプロジェクトは異なり、様々な要件を持っています。これは企業全体の実践ではなく、特定のプロジェクトに対する私たちのチームのドキュメント作成の探求です。
実装と情報の近接性
ほとんどの場合、情報が実装からどれだけ近いかを考慮する必要があります。
実装への近接性とは、情報の詳細が実装に近づくにつれてどのように増加するのかを示します。
この考え方を理解するために、以下の図を見てください。
ある距離から物体を見ると、その物体の一般的な形状（この場合は車）しか正確には分かりません。近づくにつれて、ブランド、モデル、車種などの情報がより見えるようになります。さらに近づいて車の内部を見ると、変速機の種類や内装、その他の機能が分かるかもしれません。さらに近づきエンジンルームを開けると、十分な知識があればエンジンプラットフォーム、ターボの有無など多くの詳細を理解できるでしょう。
このシナリオでは、観察対象の物体に対する私たちの距離を考慮しています。ソフトウェアドキュメントでは、「近接性」を「更新の必要性」とし、「観察対象の物体」を「実装」と考えることができます。
READMEドキュメントはプロジェクト全体のアイデアを説明します。車の例に当てはめると、READMEは車の外側にいる状態に相当します。この視点から、プロジェクトの高レベルな概要を提供する必要があります。このドキュメントが更新されるのは、車が突然ボートに変わったときだけです。
質問: マークダウンドキュメントをチェックして、マイナーなコード変更の影響を受けているかどうかを確認する頻度はどれくらいですか？
あまり頻繁ではないでしょう。実装への近接性が既に遠いため、実装の具体的な詳細を考える必要がありません。このようなドキュメントには、高レベルの情報に影響を与えない具体的な内容を含めるべきではありません。
コメントは実装に最も近い場所にあります。開発者はコメントで関数の動作を説明したり、パラメータを解説したりすることが一般的です。コメントの目的は、実装を読むだけでは得られない補足情報を提供することです。スポーツの実況中継者が選手の動きを繰り返すのではなく、観客が見逃したかもしれない洞察を提供するのと同じです。例えば、なぜ交代が行われるのか、特定のプレーに対抗するためになぜ特定の戦術が採用されているのかといった情報です。
以下のコードを見てみましょう：
/**
* According to Taxation Law #3117 individuals having dependents will have
* lowered tax as incentive granted by the government. The computation is
* base on ( taxation table -> https://taxation-table.gov.fst ).
*
* Last check on: February 27, 1620
*/
number applyTaxBaseOnDependents(number salary, number childrenCount) {
number tax = switch(childrenCount) {
1 -> salary * .05;
2 -> salary * .02;
3 -> 0;
default -> * .1;
}
return salary - tax;
}この例では、コメントがなぜこの方法で計算を行うのかという背景を追加しています。実装の背後にある決定についての洞察を提供します。関数自体を読むのが難しくないため、計算の詳細は省略されています。関数の細かい詳細を説明しないことで、いくつかの利点があります：
- 関数の詳細に小さな変更があったときにコメントを更新する手間を省けます。
- 不必要な情報の冗長性を避けられます。
- 混乱を避けられます。もしコメントが間違っていた場合、コードが間違っているのかコメントが間違っているのか？答えは両方であり、コメントを更新し忘れた開発者を見つけるためには手間がかかります。
可能であれば、変更ごとにコメントを更新しなければならないような記述は避けるべきです。車の例に戻ると、コメントは車の中に座ってその機能を見るときのようなものです。自動変速機があるのは見えますが、自動変速を実現するギアは見えていません。
参考として、業界のリーダーたちのこのアイデアについての議論を紹介します：
- Uncle Bob (Robert Cecil Martin) – Clean Code Talk
- The Elements of Programming Style – 要約へのリンク
- Kevlin Henneyの講演「Giving code a good name」 – この講演では、コメントの価値はその希少性から生まれると述べています。
実装は問題に対する私たちの定式化された解決策です。自然言語では書かれていなくても、これをドキュメントと見なすことができます。コードをドキュメントと捉えることで、すべての関数にコメントが必要ではないことを思い出させてくれます。コードをより良く構造化することで、インラインコメントの一部が不要になるかもしれません。
情報の近接性を考慮したドキュメント作成のアイデアは、「情報の展開（Progression of Information）」に拡張できますが、このアイデアはそれ自体で一つの記事になるでしょう。
オーディエンスを理解する
ドキュメントにはさまざまな用途があります。その目的に応じて、ドキュメントは対象となるオーディエンスに向けて書かれるべきです。このドキュメント作成のガイドラインのオーディエンスは、実装の内部動作を理解しており、コードにアクセスできる必要があります。
チームは大規模なコードベースで作業しており、プロジェクトを維持するためには多くの責任があります。責任にはコードのメンテナンス、データのメンテナンス、知識の保持などがあります。これらのドキュメントのオーディエンスを特定することで、ドキュメントの構造をどうすべきかのアイデアが得られます。データのメンテナンスには、より手続き的な形式が適しているかもしれません。コードのメンテナンスには、プロジェクトに適用された原則をより徹底的に説明する形式が適しているでしょう。
フォーマットルールを作成する
一貫性はドキュメントの可読性を高める上で重要な役割を果たします。参考にできるガイドはいくつかありますが、チームやプロジェクトのニーズに完全には合わないかもしれません。プロジェクトドキュメントのルールを作成することで、オーディエンスがナビゲートしやすくなり、著者が伝えるべき情報の構造をガイドするのに役立ちます。
例：
# Project A
The search for the King of Letters
## 1. Introduction
This project aims to rank the letters based on how often a letter is used based on a set of a million unique words.
## 2. Instructions
### 2.1. Environment Setup
**Steps**
1. Admit that you like Perl.
2. Install Perl
### 2.2. Generating a million words
**Steps**
1. Go to Facebook.
2. Go to your wall and grab all your posts using the Perl script.上記の例では、ユーティリティプロジェクトのREADMEファイルを作成しています。ドキュメントのルールは以下のようになります：
- 各章は章番号で示す。ルールはそのサブチャプターにも適用される。
- 章はH2、サブチャプターはH3とフォーマットする。
- 手順は実行順序を示すために番号を付ける。
フォーマットルールはたくさんありますが、これらを無視することを提案しているわけではありません。むしろ、これらのフォーマットルールの知識を基にさらに構築していくべきです。
まとめ
私たちはドキュメントにあまり考慮を払わないことで、その価値を過小評価しています。コードと同様に、構造について考えないと品質が低下する可能性があります。
