Blockly スタイルガイド

Google TypeScript スタイルガイドの手順を実施してください。

TypeScript と ES6 への移行

Blockly は元々 ES5.1 で作成されており、当時の古いバージョンの Google JavaScript スタイルガイドに準拠しています。新しく記述するコードは、現在のスタイルガイドに準拠し、let、const、class などの ES6 言語機能を使用し、必要に応じて割り当てを分解する必要があります。既存のコードが更新されたり、コンプライアンスから外されたりする可能性があります。Blockly チームは、コードの整合性とライブラリのユーザーのエクスペリエンスを考慮して、最善の決定を下すよう努めています。たとえば、スタイルガイドを遵守しなくなったパブリック関数の名前を変更しない場合があります。

すべきこと

  • lint ツールとフォーマット ツールを使用します。
    • eslint を使用して、希望するスタイルのルールを設定した .eslintrc.js ファイルを設定します。
    • 自動書式設定には prettier が使用されます。
    • npm run lint を実行してリンターを実行し、npm run format を実行してフォーマッタを実行します。
  • タブではなくスペースを使用してインデントする。
  • セミコロンを使用します。
  • 変数と関数には camelCase を使用します。
  • クラスには TitleCase を使用します。
  • 定数には ALL_CAPS を使用します。
  • すべてのコントロール構造には中かっこを使用します。
    • 例外: 単一行の if ステートメントでは中かっこを省略できます。
  • 一重引用符を使用します（JSON を記述する場合を除く）。
  • for ループで変数を再宣言する。つまり、常に for (i = 0; ...) ではなく for (const i = 0; ...) と記述します。
    • そうしないと、関数の上位にリファクタリングされた変数が孤立し、想定外のグローバルになるリスクが発生します。
  • コメントは大文字で始め、ピリオドで終わるようにします。
  • GitHub で TODO を作成して、TODO(#issueNumber) を使用してリンクします。
  • すべてに TSDoc でアノテーションを付けます。

すべきでないこと

  • タブを使用してインデントする。
  • 変数名または関数名の末尾には下線を使用します。
    • 以前の一部のコードでは、非公開のプロパティや関数にアンダースコアが使用されています。これらのコードは引き続き存在する可能性がありますが、この規則に従って新しいコードを追加しないでください。
  • snake_case を実行します。
  • 二重引用符を使用します（JSON を記述する場合を除く）。
  • 不適切な形式の TSDoc を使用します。
    • TSDoc はドキュメントの一部として自動的に公開されます。
  • TODO (username) を記述します。
    • 代わりに、TODO を使用して GitHub の問題を作成し、TODO(#issueNumber) を使用してリンクします。
  • string.startsWith を使用します。代わりに Blockly.utils.string.startsWith を使用してください。

TSDoc

Blockly チームは、TSDoc を使用してコードにアノテーションを付け、ドキュメントを生成します。クラスのすべての公開プロパティ、およびすべてのエクスポートされた関数には、TSDoc が必要です。

TSDoc コメントが正しく解析されるには、/** で始まり、*/ で終わる必要があります。

型

型は TypeScript コードに直接含まれているため、TSDoc では省略されています。残りの JavaScript ファイルのいずれかを編集する場合は、Closure Compiler のドキュメントに従って型アノテーションをインクルードします。

公開設定

Blockly ライブラリ内でのみアクセスする必要がある関数またはプロパティには、@internal アノテーションを付ける必要があります。これにより、これらのプロパティは一般公開ドキュメントに記載されなくなります。その他の可視性修飾子は、TSDoc ではなく TypeScript コードに直接配置する必要があります。

プロパティ

プロパティの TSDoc にはプロパティの説明を含める必要があります。プロパティについては、説明を省略しても構いません。

/**
  *   The location of the top left of this block (in workspace coordinates)
  *   relative to either its parent block, or the workspace origin if it has no
  *   parent.
  *
  *   @internal
  */
relativeCoords = new Coordinate(0, 0);

関数

関数のアノテーションには以下を含める必要がある

  • 関数の説明
  • パラメータごとに 1 つの @param タグ（以下を含む）
    • 名前
    • 説明
  • 関数が値を返す場合は @returns タグと戻り値の説明。

関数、パラメータ、戻り値の説明は、その説明が明白な場合は省略できます。

例:

/**
 *   Find the workspace with the specified ID.
 *
 *   @param id ID of workspace to find.
 *   @returns The sought after workspace or null if not found.
 */
export function getWorkspaceById(id: string): Workspace | null {
  return WorkspaceDB_[id] || null;
}