スタイルガイド

Google TypeScript スタイルガイドに沿って作成します。

TypeScript と ES6 への移行

Blockly は、古いバージョンの Google JavaScript スタイルガイドに準拠して、元々 ES5.1 で記述されていました。新しく作成するコードは、現在のスタイルガイドに準拠し、let、const、class、必要に応じて構造化解除代入などの ES6 言語機能を使用する必要があります。既存のコードは更新される場合もあれば、コンプライアンス違反のままになる場合もあります。Blockly チームは、コードの整合性とライブラリのユーザー エクスペリエンスを考慮して最善の判断を下そうとしています。たとえば、スタイルガイドに準拠していない公開関数の名前を変更しない場合があります。

すべきこと

  • lint ツールとフォーマット ツールを使用する。
    • Google では eslint を使用しており、好みのスタイルのルールが設定された eslint.config.mjs ファイルがあります。
    • 自動フォーマットには prettier を使用します。
    • npm run lint を実行してリンターを実行し、npm run format を実行してフォーマッタを実行します。
  • タブではなくスペースでインデントを設定します。
  • セミコロンを使用します。
  • 変数と関数には camelCase を使用します。
  • クラスには TitleCase を使用します。
  • 定数には ALL_CAPS を使用します。
  • すべての制御構造にかっこを使用します。
    • 例外: 1 行の if ステートメントでは、中かっこを省略できます。
  • 単一引用符を使用します（JSON の記述時を除く）。
  • for ループで変数を再宣言。つまり、常に for (i = 0; ...) ではなく for (const i = 0; ...) を記述します。
    • そうしないと、関数の上位でリファクタリングした後に、変数が孤立し、予期しないグローバル変数になるリスクが高まります。
  • コメントの先頭は大文字で、末尾はピリオドにします。
  • TODO を含む GitHub の問題を作成し、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;
}