Typescriptの関数にブロックコメントはつけるべき？
開発環境
- typescript 5.7.2
前提
本記事は個人的見解が強めです。
あくまでも、そんな意見もあるんだなというレベルで見ていただけると幸いです。
本題
① ブロックコメントは ”必要な場合のみ” 付けるべき
TypeScriptでは、関数にブロックコメントを付けることで以下の利点があります。
- 可読性の向上: 関数の目的や仕様を明確にすることで、コードを読む人に意図が伝わりやすくなります。
- VSCodeでの補助機能: コメントをJSDoc形式で記述しておけば、VSCode上で関数をホバーした際に補足情報が表示されます。これにより、ドキュメントを参照しなくても関数の詳細を確認できます。
- 自動ドキュメント生成: JSDoc形式のコメントは、TypeDoc などのツールを利用することでHTML形式のドキュメントとして出力できます。これにより、コードとドキュメントの整合性を保ちながら開発を進めることができます。
以下は例としてtruncate関数を用いたブロックコメントです。
/**
* 文字列を指定した最大長で切り詰める関数
* @param str - 対象の文字列
* @param maxLength - 最大文字数
* @returns 切り詰められた文字列
*/
export const truncate = (str: string, maxLength: number): string => {
if (str.length <= maxLength) return str;
return str.slice(0, maxLength) + '...';
};その理由
コメントがない場合、コードを読む人に混乱を招くことがあります。
たとえば、truncate関数を含むプロジェクトで Tailwind CSS の truncate クラスを同時に使用するケースを考えてみましょう。
- Tailwind CSS のtruncateクラス: テキストを省略表示する CSS クラス
- TypeScript のtruncate関数: 文字列を手動で切り詰めるロジックを実行
この場合、コメントがないとどちらを使うべきかが不明確になる可能性があります。
しかし、上記のようにコメントを付けておけば、それぞれの用途を簡単に把握できます。
/**
* Tailwindの`truncate`クラスでは処理できない文字列をカスタマイズして切り詰めるための関数
*/
export const truncate = (str: string, maxLength: number): string => {
// 実装...
};このように、関数の意図や背景を記述しておくことで、類似の機能との使い分けの判断がしやすくなります。
ただ、個人的には不要なケースもある
もちろん、すべての関数にコメントを付けるべきではありません。特に以下のような場合では、コード自体が十分に自己説明的であり、コメントは不要です。
export const add = (a: number, b: number): number => a + b;このような簡潔な関数では、型情報と関数名だけで意図が伝わるため、コメントを追加する必要性は低いでしょう。
その理由
- コードのメンテナンス性: コメントがコードの変更に追従しない場合、誤解を招くリスクがあります。特に簡単な関数では、コメントの更新がかえって手間となることもあります。
- 過剰なドキュメンテーションコスト: シンプルな関数にまでコメントを付けることは、時間の無駄になる可能性があります。
さいごに
TypeScriptの関数にブロックコメントを付けるべきかどうかは、プロジェクトの状況や関数の複雑さによります。
特に複雑なビジネスロジックや第三者との協働が多い場合、コメントは重要なコミュニケーションツールとなります。 ただし、コード自体が意図を十分に伝える場合はコメントを省略し、必要最低限のドキュメントで効率的に進めるのが理想です。
おまけ
記事の中で触れましたが、コメントをJSDoc形式で記述することで、VSCode上で関数をホバーした際に補足情報が表示されることは個人的にはそこまでのメリットではないです。
なぜなら、VSCodeを利用していると（他のツールもそうかもしれませんが・・）関数を「command + クリック」することで、関数のファイルまでジャンプすることができるからです！