ライブラリ作成者向けガイドラインの紹介

このガイドでは、ライブラリを設計する際に考慮すべきベストプラクティスとアイデアをまとめています。

効果的なライブラリであるためには、特定の基本的な目的を達成する必要があります。具体的には、次のとおりです。

• その問題領域を定義し、定義された問題を解決するための一連の関連する機能要件を実装すること。 たとえば、HTTPクライアントはすべてのHTTPリクエストタイプをサポートし、さまざまなヘッダー、コンテンツタイプ、ステータスコードを理解することを目指す場合があります。
• 問題領域に適切な非機能要件を満たすこと。これには通常、性能、信頼性、セキュリティ、ユーザビリティが含まれます。 これらの要件の相対的な重要性は大きく異なります。たとえば、バッチ処理用に設計されたライブラリは、デイトレードを目的としたものと同じレベルの性能を必要としない場合があります。

機能要件と非機能要件を特定し、定義するプロセスは、ソフトウェアエンジニアリングで広範囲に研究されてきた複雑なトピックです。 このガイドでは、これらのトピックは範囲外であるため、深くは扱いません。

このガイドの主な焦点は、ユーザーにとって関連性を保ち、人気を維持するためにライブラリが持つべき特性を探求することです。これらの特性には次のものが含まれます。

• 認知的複雑性を最小限に抑える: すべての開発者は、コードの可読性と保守性を考慮する必要があります。他の人がAPIを読み、理解し、使用するために必要な精神的労力を減らすことが重要です。これを達成するには、明確で一貫性があり、予測可能で、デバッグしやすいライブラリを作成することが含まれます。
• 後方互換性: APIの新しいバージョンをリリースする際には、既存のAPIが引き続き動作することを確認してください。破壊的変更については、事前に明確に伝え、文書化してください。ユーザーが新しいAPIまたは設計変更を導入するための、直接的で明確かつ段階的な道筋を提供してください。
• 有益なドキュメント: ライブラリに付属するドキュメントは、関数や型宣言を繰り返す以上のことを行う必要があります。包括的であり、ライブラリの対象読者向けに具体的に調整されている必要があります。さまざまなユーザーロールのニーズとシナリオを正確に反映し、過度に単純化されたり、複雑になりすぎたりすることなく、本質的な情報を提供する必要があります。常に明確な例を含め、説明文と実用的なコードサンプルとのバランスを取るようにしてください。

さらに、マルチプラットフォーム対応のKotlinライブラリを構築することで、さまざまな環境を対象とするプロジェクト全体での適用性を広げることができます。 APIを共通コードとプラットフォーム固有コードの両方で確実に動作するように設計することで、サポートされるすべてのターゲットにおけるライブラリの汎用性とユーザビリティを向上させることができます。

以下のセクションでは、これらの特性についてさらに詳しく掘り下げ、ライブラリのユーザーに可能な限り最高の体験を提供するための実践的なアドバイスを提供します。

次のステップ

• 認知的複雑性を最小限に抑えるで、認知的複雑性を最小限に抑えるための戦略を探求します。
• 後方互換性で、後方互換性を維持する方法について学びます。
• 効果的なドキュメント作成の実践に関する包括的な概要については、有益なドキュメントを参照してください。
• マルチプラットフォーム対応Kotlinライブラリの構築で、マルチプラットフォームライブラリを構築するためのベストプラクティスを見つけます。