なぜこれが起こっていますか。 確かに、必要な機能または同じNPMパッケージを備えたライブラリを探しているときに、次のようなものが見つかりました。
基本的にはコードの一部です。 それが何であるか、何をするのか、どのように使用するのかについての説明はありません。 これがNPMパッケージである場合、おそらくあなたは彼の腸に入り、それがどのように機能するかを理解し、あなた自身の責任でそれを使うことができます。 しかし、それがサービスである場合、何もすることはありません。どのメソッドがあり、どのデータが入力されるのかを把握しようとはしません。
パブリックAPIが見つかった場合、何が期待できますか？ おそらくこのようなもの：
これはバベルのNPMです。 それが何であるか、何をするのか、そしてそれをどのように使用するのかを伝えます。 つまり、一般に何かを投稿するときは、ドキュメントを添付する必要があります。 そうでなければ、それは単に無意味です。
ドキュメント
フロントエンドでは、フレームワークとライブラリがほぼ毎日表示されるため、ランディングページも提供することが非常に一般的になりました。
実際、これは、このAPIが解決するタスク、競合他社よりも優れている理由、必要がない場合でも間違いなく使用する必要がある理由などを説明する広告です。 また、このランディングページには既にドキュメントへのリンクがあり、通常は「入門」セクションと「 APIリファレンス 」セクションがあります 。
はじめには、APIを最初に見るユーザー向けのセクションです。 このセクションでは、ダウンロードする場所、組み立てる方法、起動する方法などについて説明します。 ここでは、製品のさまざまな機能の使用方法を説明することも習慣的です。 たとえば、APSの「はじめに」では 、小さなアプリケーションを使用してさまざまな機能を段階的に追加し、アプリケーションの一部を作成できる本格的な戦闘ソリューションを提供します。
APIリファレンスは、APIの使用方法を知っていて、プロパティの名前またはメソッドのパラメーターを明確にするだけの上級ユーザーを対象としています。
ドキュメントは最新の状態に保つ必要があるため、複雑で高価なように見えるかもしれませんが、幸いなことに、これは少し間違っています。 皆さんが自分自身を愛し、コメント付きのコードを書くことを願っています。 最も可能性が高いのは、モジュールとメソッドをJSDoc形式で記述することです。これは、それが業界の事実上の標準だからです。 そして、Reactを使用する場合、data-propsがあります。 コードによってJSDocをコンパイルし、好きなようにさまざまなビューアで表示できるJSON辞書を作成できるユーティリティが多数あります。つまり、並べ替え、検索、強調表示、分類、その他すべての機能を備えています。 TypeScriptも優れています。
ドキュメントには例が必要です。 そして、彼らが働くことは非常に重要です。 ドキュメントの非実用的な例のように、プロジェクトの印象を損なうものは何もありません。 驚くべきことに、これは考えられるほどまれに起こりません。
サンドボックス
さて、例がありますが、私たちは人々を助けたようです。 しかし、通常、人々はこれを自分で試して、実験する、つまり、これらの例から問題を解決することができるかどうかを自分で理解したいと考えています。 そして、彼らは何もダウンロードもインストールもせずに、素早く簡単にそれをしたいのです。 また、これは解決するタスクでもあります。なぜなら、私たちはJavaScript開発者であり、ブラウザーですべてを実際に実行でき、長い間、私たちの素晴らしいサンドボックスであるcodepen 、 jsfiddle 、 jsbinがありました 。 APIを使用して独自の小さなスニペットを作成し、ドキュメントへのリンクを追加して、すぐにジャンプして実験することができます。
パブリックサンドボックスのフレームワーク内でcr屈になり、独自に作成したい場合があります。 これもそれほど難しくありません。ブラウザにコードエディタのすばらしいライブラリが2つあるからです。 1つはCodeMirrorで 、たとえばjsfiddleやFirefox DevToolsで使用されます。 2番目はAceで 、多くのお気に入りであるAtomで使用されます。 APSでは、ささいなことをせず、CodeMirrorを使用して独自のパブリックサンドボックスを作成しました。
最初は、初心者がサンドボックスを使用することを想定していたため、ドキュメントのサンプルをサンドボックスで開くことができるように作成し、コード補完もすぐに追加しました。 また、これにはロケット科学もありません。APIのJSONディクショナリがあり、コードエディタに簡単にフィードできるからです。 そして、これはブラウザーエディターだけでなく行うことができます。 たとえば、私はSublimeでそのようなコード補完を取得することができました。 後で、APIバージョンの選択、複数のユーザーによる1つのコードの同時作業などを追加しましたが、これらはすべてオプションです。 主なことは、コードエディタと結果をIframeで使用して簡単なサンドボックスを作成することはまったく難しくないということです。 また、Reactには、このようなサンドボックスの既製のジェネレーターがあります。
ユーザーインタラクション
ここでドキュメントを作成し、サンドボックスを作成しました。そこで停止できるようです。 ただし、APIの開発を停止する場合のみです。 さらに開発したい場合は、ユーザーと対話することをお勧めします。 そして、彼らの「感謝」の叫び声が聞こえないように、可能な限り最高の壁から新しい機能を投げつけないようにします。 これを行う最も簡単な方法は、GitHubの問題、またはメッセンジャーのすべての種類のチャットルームとチャネルを使用することです。 しかし、ユーザーがあなたに語らないこともあります。 たとえば、ある人が問題を抱えていて、どうにかしてそれを解決し、松葉杖で彼に任せて、この松葉杖でctrl-c / ctrl-vをプロジェクトからプロジェクトに移しました。 しかし、そのようなシナリオを提供しなかったことが判明する可能性があり、最悪の場合、ユーザーはプライベートAPIの一部にアクセスすることさえできます。 これに対処する方法は？
最初の方法は、さまざまなメトリックを収集することです。つまり、メソッド呼び出しをログに記録し、どこかに送信します。 どのモジュールとウィジェットが作成されたか、どのパラメーターなどを使用して追跡できます。 もちろん、コードが実行された環境（ブラウザーバージョン、モバイルデバイス）を監視する必要もあります。これは、世界中のブラウザーの使用に関する統計は有用なものですが、ユーザーは、最新のブラウザーのみを使用するスタイリッシュ/トレンディ/若者になることがあるためです。何らかの理由でIEのサポートに時間と労力を浪費しています。
相互作用の2番目の方法は、パブリックAPIの使用に関心がある大企業-特別なトレーニングチームの作成に適しています。 YandexがさまざまなサブボトニックとmitapでBEMを使用して、私たち全員の脳をどのように選択していたか覚えていますか？ オーディンには、世界中を走り、人々にAPSを教えるトレーナーのチームもあります。 教室では、トレーナーは人々が最も困難な場所、プロジェクトからプロジェクトへと愛情を込めて移された松葉杖を挿入する場所を確認し、人々が踏んだこれらの歩道を慎重に舗装し、便利な道路にします。
下位互換性
まあ、ユーザーとの相互作用を確立し、彼らが求めるAPIを変更し、より良く、より良くしています...そして、ここでは後方互換性と呼ばれる鉱山を待っています。 自宅で静かに静かに眠っている、または休暇中に楽園の島でリラックスしていると、上司はすべてが失われ、すべてが壊れ、サーバーが横たわって、クライアントが去り、石膏が取り除かれ、何かをすることを叫びます。
1か月間、何も変わっていないことを覚えて理解し始めます。 それを整理するために登ります-マイナーバージョンを更新したいくつかの小さなライブラリがあり、それをサポートする人は方法Aが必要なことをしていないと判断し、その動作を変更しました。 しかし、あなたは古い振る舞いの方法を期待していました。 そして、あなたのコードは古い振る舞いを期待していました。 このライブラリの所有者として行動すると、すべてのユーザーがすぐに失われます。
これに対処する方法は？
ここではオリジナルのものは提供できません。テスト、テスト、そして再びテストのみです。 さらに、テストはコードをカバーするだけでなく、パブリックAPIをカバーするためのものです。 Odinの私たちは、この完全に全体主義的なアプローチに取り組み、プルリクエストの段階で、まずカバレッジのラインによる劣化、次にパブリックAPIによる劣化をチェックしました。 JSONディクショナリがあるため、それらをカバレッジレポートと比較し、テストでカバーされなかったメソッドを見つけることができます。 そのようなものが現れた場合、チェックは失敗したとみなされ、そのようなプルリクエストはマスターブランチと結合できません。
合計
パブリックAPIを快適に使用するには、何をする必要がありますか？
まず、 ドキュメントを書きます 。 誰もドキュメントを使用しないため、ドキュメントなしでパブリックドメインに何かを公開することは、少なくとも愚かです。 そして、ドキュメントには興味深いライフハックがあります。 APIにまだ慣れていない仲間の初心者に、ドキュメントに従ってAPIを使って何かをするよう依頼してください。 なぜなら、ドキュメントを読むとき、APIデバイスの知識にそれを「課し」、すべてを理解するからです。 しかし、新しい人はそのような知識を持っていない、彼は文書に従って厳密にそれを行い、実践が示すように、彼は浅瀬を見つけなければなりません。 ボーナスとして、彼はすでにあなたがここで何をしているのか、なぜこれがすべて必要なのかをある程度知っている仕事に参加します。
第二に、真空状態で球形の馬を作らないように、 ユーザーと対話する必要があります 。
そして第三に、 テストを書く必要があります 。 さらに、すべてを3メートルのコンクリート層で埋め、変更を完全に制御します。つまり、メジャーバージョンが変更されたときにのみパブリックAPIが変更されます。