writing-comments

コメントの記述

目的

このリポジトリのコメントは、書かれてから数か月、あるいは数年後に、今あなたが持っている背景情報を一切知らないコントリビューターに読まれます。このスキルでは、その読者がどのような人か、各種コメントの目的、そして禁止されているパターンを定義します。

対象範囲

このスキルが対象とするのは、TypeScript／JavaScript のソースに含まれるコントリビューター向けコメントです。エンドユーザー向けドキュメントには適用されません。

• packages/astro/src/types/public/config.ts および packages/astro/src/core/errors/errors-data.ts にある @docs タグ付きの JSDoc ブロックは、外部の docgen ツールによって抽出され、Astro のドキュメントサイトに公開されます。それらについては packages/astro/src/core/errors/README.md に従い、ドキュメントチームのレビューを受けてください。types/public/** が変更されると、CI がリファレンスを再生成します。
• types/public/** にあるその他の JSDoc は、エディターの IntelliSense を通じてユーザーに表示されます。ソースを読むコントリビューターではなく、サイトを構築する Astro のユーザーに向けて記述してください。

以下はすべて、HEAD のソースを読むコントリビューターを対象としています。

読者

TypeScript の知識は十分にあるものの、現在の背景情報にアクセスできない Astro のコントリビューターに向けて書いてください。ここでの会話にも、プルリクエストにも、イシューにも、差分にもアクセスできません。読者が見られるのは、HEAD のリポジトリだけです。

ここから、次の 2 つの帰結が直接導かれます。

1. 変更の経緯を説明しないでください。「今では」「以前は」「もはや〜ない」「新しいアプローチ」といった言葉は、唯一のアプローチしか存在しない HEAD では意味を持ちません。コードがどのように機能するかを述べ、その経緯は述べないでください。（@deprecated の通知は例外です。このコードベースの規約を参照してください。これは読者が知る必要のある、コントラクトの将来について説明するものです。）
2. **レビュアーに語りかけないでください。**変更の正当性を主張するコメント（「これは X を適切に処理します」など）は、ソースではなくプルリクエストの説明に記載してください。コメントでは、現状のコードを恒久的に正当化する必要があります。

3 種類のコメントと、それぞれの役割

種類	構文	役割	含める内容
ファイル／モジュールの概要	ファイル冒頭の /** */	説明	モジュールが存在する理由、モジュールが定義する概念や用語、各要素の関係、設計の根拠
アイテムのドキュメント	宣言の直上にある /** */	リファレンス	コントラクト：動作、パラメーター、戻り値、スローされるエラー、不変条件。中立的かつ事実に即した記述
インラインコメント	本体内の //	根拠	コードだけでは表現できないことのみ：制約、回避策（イシューへのリンク付き）、自明でない結合

それぞれの役割を混同しないでください。実装の詳細は /** */ のコントラクトに含めず、本体内の // コメントとして記載してください。コントラクトをインラインコメントに分散させず、宣言の上に記載してください。

動作のドキュメント化

項目のドキュメントが必要な場合は、実装を翻訳するのではなく、人が読むための契約を記述してください。すべての関数に JSDoc を付ける必要はありません。名前、型、構造から、基本的な動作が分かるようにしてください。

• 関数が何を返すのか、または何を実現するのかを、平易な言葉で説明するところから始めます。
• 1 文につき主な内容を 1 つに絞り、短めまたは中程度の長さにします。
• 呼び出し側に不要な、Astro 内部の専門用語は避けてください。技術用語が必要な場合は、同じ段落内で説明します。
• 呼び出し側が意外に感じる可能性のある注意事項を説明します。フォールバック動作、処理の上限、曖昧な結果、オーバーロードの選択順、副作用、undefined、null、空の結果、その他の不確定な値を返す条件などが該当します。
• 呼び出し側が判別または回復する必要があるエラーは、スローされるものを記載します。
• 呼び出し側が動作を理解したり、API を安全に使用したりするために必要な場合を除き、実装の詳細は記述しません。

動作がシグネチャからはっきり分からない関係に依存する場合は、例を追加します。Astro や TypeScript でよくあるケースは次のとおりです。

• どのオーバーロードが選択されるか。
• 引数が省略可能なパラメーターや rest パラメーターにどう対応するか。
• 別の場所で実装または再エクスポートされているシンボルが、どの公開 Astro エントリーポイントから利用できるか。
• 曖昧なルート、不完全な設定、コンテンツの欠落に対するフォールバック動作。
• 型から意味が明らかでない結果。

コードブロックの前に、例の説明を文章で加えます。例が何を示し、どのような結果が期待されるかを明記してください。コード片は最小限で自己完結したものとし、Astro ユーザー、またはその契約を担う内部呼び出し元の視点で記述します。

モジュールのドキュメントでは、長期にわたって維持される概念、アーキテクチャ上の境界、または設計上の理由を説明します。ファイルの要約として個々のエクスポートを列挙しないでください。シンボルの追加や名前変更に伴い、そうした一覧は古くなります。説明すべき長期的な概念がないモジュールには、簡潔な 1 行の説明を付けるか、概要を記載しないでください。

削除テスト

コメントを書く前に、次のことを確認してください。この情報は、コードだけから読者が把握できない内容ですか？

• 名前、型、構造からすでに分かる情報なら、コメントには書きません。名前から内容が伝わらない場合は、名前を改善します。
• コメントで説明する必要がある情報：不変条件、理由、別の場所にあるコードとの結び付き、リンク付きの回避策、依存関係の意外な動作、モジュールが定義する専門用語。

後から編集するときも、同じテストを逆向きに適用します。条件を満たさなくなったコメントは、放置せず削除してください。

回避策には Issue へのリンクを付ける

このコードベースでは、回避策を一貫して根拠となる情報源に結び付けています。回避策、HACK、リグレッションガード、または依存関係の意外な動作を説明するコメントには、根拠となる GitHub の Issue または PR へのリンクを必ず付けてください。リンクがあれば、将来の読者はその回避策がまだ必要かどうかを判断できます。

// Handle recommended nanostores. Only @nanostores/preact is required from our testing!
// Full explanation and related bug report: https://github.com/withastro/astro/pull/3667
'@nanostores/preact',

リンクのない回避策は、誤りと見分けがつきません。

禁止パターン

次の行の説明。 見つけたらすぐに削除してください。

// Increment the generation counter
generation += 1;

変更履歴の説明。 現在形で理由を説明する形に書き換えてください。

// BAD: We now resolve lightningcss from the user's root instead of ours.
// GOOD: lightningcss is an optional peer dep, so it resolves from the user's project root.

レビュアーに向けた正当化。 論拠は PR に記載してください。

// BAD: This correctly handles the multi-encoded path from the bug report.
// GOOD: A path still encoded after MAX_DECODE_ITERATIONS is rejected, so
//       middleware and routing can never disagree on the decoded path.

JSDoc の言い換え。 宣言の名前を言い換えただけの /** */ ブロックには、何の意味もありません。

// BAD:
/** Compiles the styles. */
function compileStyles(...)

// GOOD:
/** Rewrites relative `url()` references in `css` against `base`, leaving
 *  absolute and data URLs untouched. */
function compileStyles(...)

曖昧な表現。 「一部のケース」「さまざまな理由」「エッジケースに対応」「など」――具体的に挙げるか、その文を削除してください。

絵文字。 ソースコードやコメントを含め、使用は禁止されています（リポジトリ全体のポリシー）。

場当たり的なセクション見出し（// ----- helpers -----、// ==== TYPES ====）。 このコードベースでは // #region による折りたたみの慣例はありません。見出しを追加しないでください。見出しが必要なほどファイルが長い場合は、飾りを付けるのではなく、ファイルを分割してください。

このコードベースの規約

JSDoc タグ。 @param name - description、@returns、@throws で契約を記述します。シグネチャだけでは曖昧な場合に限り、型を波括弧で囲みます（@returns {Promise<string>}）。自明でない使い方には、フェンス付きの ```js ブロックを使って @example を記述します。

相互参照。 名前を変更したときに参照も更新され、エディターから参照先へ移動できるよう、名前だけを書くのではなく {@link Symbol} / {@linkcode Symbol} を使います。

@internal。 公開 API の対象外であることを示します。これはあくまで規約です。このコードベースには typedoc も api-extractor もなく、これを取り除くことはできないため、意図を説明するだけで、アクセス修飾子の代わりにはなりません。

@deprecated。 移行方法を記述し、その後に削除時期の目安を示します。

/** @deprecated Use the instance method `cookies.consume()` instead. This will be removed in Astro 7 */

シンボルが非推奨であると述べるだけでなく、代わりに何を使うべきかを記述します。この未来形の注記は、読者に必要な契約情報であり、禁止されている変更履歴の説明ではありません。

TODO。 後回しにする作業には // TODO: を使い、追跡用の issue がある場合はリンクします。破壊的変更の期間まで保留する作業には、確立された書き方である // TODO: remove in Astro <N> を使います。このコードベースに FIXME はありません。追加しないでください。

既存コードの編集

• 既存のコメントを維持します。変更によって動作が変わる場合は、具体的な説明を拡張または修正してください。一般的な文言に置き換えてはいけません。苦労して得た背景情報を削除するより、コメントが多少古くなるほうがましです。
• 変更によってコメントが事実に反するものになった場合は、同じ差分で修正します。古いコメントは、コメントがないよりも悪いものです。
• 周囲の情報量に合わせます。詳細に文書化されたモジュールでは、新しい項目にも同じ水準の説明を付けます。コメントの少ないモジュール全体に、コメントを一律に追加しないでください。

完了前の自己確認

コメントに触れた作業を終えたら、コードの変更とは切り離して、差分に含まれるコメントだけを読み直します。

1. それぞれのコメントは削除テストに合格しますか？
2. 会話、変更そのもの、またはレビュー担当者に言及しているコメントはありませんか？
3. 回避策にはすべて、関連する issue または PR へのリンクがありますか？
4. 差分を見られない読者でも、それぞれのコメントを理解できますか？

問題があるものは修正するか削除します。削除を基本としてください。コメントがないほうが、誤解を招くコメントを残すよりも低コストです。

参考資料

• Diátaxis — 上記の説明／リファレンス／根拠の分け方の基盤となるフレームワークです。
• packages/astro/src/core/errors/README.md — エンドユーザー向けドキュメントである、@docs タグ付きのエラー項目について説明しています。
• TSDoc — TypeScript のドキュメントコメントで使うタグのリファレンスです。