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; ...) と記述します。
    • そうしないと、関数の上位でリファクタリングした後に、変数が孤立し、予期しないグローバル変数になるリスクが高まります。
  • コメントの先頭は大文字で、末尾はピリオドで終わらせます。
  • 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;
}