ライブラリ作成者向けガイドラインの紹介
このガイドには、ライブラリを設計する際に考慮すべきベストプラクティスとアイデアの要約が含まれています。
効果的なライブラリにするためには、いくつかの基本的な目的を達成する必要があります。具体的には、以下の通りです。
自身の問題ドメイン (problem domain) を定義し、定義した問題を解決する一連の関連する機能要件を実装すること。 例えば、HTTPクライアントは、すべてのHTTPリクエストタイプをサポートし、さまざまなヘッダー、コンテンツタイプ、ステータスコードを理解することを目指すかもしれません。
問題ドメインに適した非機能要件を満たすこと。これらには通常、パフォーマンス、信頼性、セキュリティ、ユーザビリティが含まれます。 これらの基準の相対的な重要性は大きく異なります。例えば、バッチ処理用に設計されたライブラリは、デイトレード向けのライブラリほど高いパフォーマンスを必要としない場合があります。
機能要件および非機能要件を特定して定義するプロセスは、ソフトウェアエンジニアリングにおいて広く研究されている複雑なトピックです。 このガイドでは、これらは範囲外であるため、詳細には扱いません。
このガイドの主な目的は、ライブラリがユーザーにとって価値があり、人気を維持し続けるために備えるべき特性を探ることです。これらの特性には以下が含まれます。
- 精神的負荷の最小化 (Minimize mental complexity): すべての開発者は、コードの読みやすさと保守性を考慮しなければなりません。他人があなたのAPIを読み、理解し、使用するために必要な精神的負荷を軽減することが不可欠です。これを実現するには、明確で、一貫性があり、予測可能で、デバッグが容易なライブラリを作成する必要があります。
- 後方互換性 (Backward compatibility): APIの新しいバージョンをリリースする際は、既存のAPIが動作し続けることを確認してください。破壊的変更 (breaking changes) については、十分な余裕を持って明確に伝え、ドキュメント化してください。ユーザーが新しいAPIや設計変更を採用するための、単純明快で段階的な経路を提供してください。
- 有益なドキュメント (Informative documentation): ライブラリに付随するドキュメントは、関数や型の宣言を繰り返すだけでは不十分です。ドキュメントは包括的で、特にライブラリの対象読者に合わせて調整されている必要があります。さまざまなユーザーの役割のニーズやシナリオを正確に反映し、単純すぎたり複雑すぎたりすることなく、不可欠な情報を提供できるようにしてください。常に明確な例を含め、説明文と実践的なコードサンプルのバランスをとってください。
さらに、Kotlinライブラリをマルチプラットフォーム対応で構築することで、さまざまな環境をターゲットとするプロジェクト全体での適用範囲を広げることができます。共有コードとプラットフォーム固有のコードの両方で確実に動作するようにAPIを設計することで、サポートされているすべてのターゲットにおけるライブラリの汎用性とユーザビリティを向上させることができます。
以降のセクションでは、これらの特性をさらに深く掘り下げ、ライブラリのユーザーに可能な限り最高の体験を提供する方法について、実践的なアドバイスを提供します。
次のステップ
- 精神的負荷の最小化 で、精神的負荷を最小限に抑えるための戦略を確認してください。
- 後方互換性 で、後方互換性の維持について学んでください。
- 効果的なドキュメント作成の慣行に関する広範な概要については、有益なドキュメント を参照してください。
- マルチプラットフォーム向けKotlinライブラリの構築 で、マルチプラットフォームライブラリを構築するためのベストプラクティスを確認してください。