Effective Rust ―Rustコードを改善し、エコシステムを最大限に活用するための35項目

5章ツール

Titus Winters（Googleの C++ライブラリリーダ）は、ソフトウェアエンジニアリングを、時間軸にまたがったプログラミング、ある場合には時間軸と人々にまたがったプログラミングである、と定義した。長い時間軸、広いチームで見ると、コードそのものではなく、それを含むコードベース全体が重要なのだ。

Rustを含む近代的な言語はこのことを理解しており、プログラムを実行可能なバイナリコードに変換する（コンパイラ）ことをはるかに超えた機能を持つ、ツールのエコシステムを保持している。

本章は、Rustのツールエコシステムについて説明し、これらの基盤を有効に活用するための一般的なアドバイスを行う。当然だが、これらはコードの規模に相応に行う必要がある。2回しか実行しない使い捨てのプログラムに対してCIを設定し、ドキュメントをビルドし、6種類のテストを書くのはやりすぎだ。しかし、本章で示す内容のほとんどは、やるだけの価値がある。ツールを導入に少しだけ投資をすれば、十分なメリットが得られる。

項目27：パブリックインターフェイスのドキュメントを書こう

あるクレートが誰か別のプログラマに使われるのであれば、クレートの内容、特にパブリックAPIに対して、ドキュメントを追加すると良い。そのクレートが、短命の使い捨てコードではないなら、「別のプログラマ」には、そのコードの詳細を忘れてしまっているであろう「未来の自分」も含まれる。

これはRustに特有のアドバイスではないし、新しい話でもない。例えばEffective Java（https://www.oreilly.com/library/view/effective-java-2nd/9780137150021/）第2版（2008）の項目44は、「公開されるAPIの要素すべてにドキュメントコメントを書こう」となっている。 ...