メインコンテンツへスキップ

コーディング原則

エラーメッセージ​

適切なエラーメッセージは、ユーザーに次に何をすべきかを伝えます。Playground の公開 API によってスローされるエラーに曖昧さがあると、開発者は問題をオープンすることになります。

たとえば、ネットワーク エラーを考えてみましょう。エラーの種類を推測し、次の手順をまとめた関連メッセージを表示できるでしょうか?

  • ネットワークエラー: 「インターネット接続が不安定です。ページを再読み込みしてください。」
  • 404: 「ファイルが見つかりませんでした。」
  • 403: 「サーバーがファイルへのアクセスをブロックしました。」
  • CORS: ブラウザのセキュリティ機能であることを明確にし、詳細な説明へのリンク（ MDN などの信頼できる情報源）を追加します。ユーザーにファイルを raw.githubusercontent.com などの別の場所に移動することを提案し、サーバー上で CORS ヘッダーを設定する方法を説明したリソースへのリンクも提供します。

コードのフォーマットとリンティングは自動的に行われます。安心して入力し、あとは機械に任せましょう。

パブリック API​

Playground は、API スコープを可能な限り狭くすることを目指しています。

パブリック API は追加は簡単ですが、削除は困難です。新しい API を導入するには 1 件の PR で済みますが、削除するには 1,000 件もの PR が必要になることもあります。特に、他のプロジェクトで既にその API を使用している場合はなおさらです。

  • 不要な関数、クラス、定数、その他のコンポーネントを公開しないでください。

ブループリント​

ブループリントは Playground を操作するための主要な手段です。これらの JSON ファイルは、Playground が順番に実行する一連のステップを記述します。

ガイドライン​

ブループリントのステップは簡潔かつ焦点を絞ったものでなければなりません。1 つのことに集中し、それをしっかりと実行する必要があります。

  • 新しいステップを作成する必要がある場合は、まず既存のステップをリファクタリングしてみてください。
  • それでも不十分な場合は、新しいステップが新しい機能を提供することを確認してください。既存のステップの機能を複製しないでください。
  • ステップが複数回呼び出されることを想定してください。
  • 特定の順序で実行されることを想定してください。
  • それを検証するための単体テストを追加してください。

ブループリントは直感的でわかりやすいものでなければなりません。

  • 省略可能な引数は必須にしないでください。
  • 単純な引数を使用してください。例えば、path ではなく slug を使用してください。
  • 定数は仮想 JSON ファイルで定義してください。PHP ファイルを変更しないでください。
  • Blueprint の TypeScript 型を定義してください。Playground はこのようにして JSON スキーマを生成します。
  • Blueprint ステップを処理する関数を記述してください。定義した型の引数を受け入れてください。
  • ドキュメント文字列に使用例を記載してください。これは自動的にドキュメントに反映されます。