More than 3 years have passed since last update.

コメントやコミットメッセージについてまとめる

Posted at 2022-04-02

どんな内容か

主観もまじっていますが、とても簡単なことでコード可読性があがります。

質の良いコメントやコミットメッセージを残してコードの歴史を追いやすくしたり、実装者の意図を伝えて新たに参画した人が読みやすくなります。

現場によって異なることもあるので参考程度に留めていただければと思います。

関数やクラスのコメントには//よりも/** ... */ を使用すると良いです。
カーソルを合わせた際に関数の説明欄が表示されるようになるので非常に便利です。

/**
 * 足し算するやつ
 * @param a １つめの数値
 * @param b ２つめの数値
 * @return aとbの合計値
 */
export const plus = (a: number, b: number) => {
  return a + b;
};

function getType() {
  // set the default type to 'no type'
  const type = this.type || "no type";

  return type;
}

定数がなぜその値なのか背景をかくと良いかと思います。

// 顧客要件により画面に表示する質問の回数は３回 まで などと背景を書く
export const NUM_QUESTION = 3;

コメントの先頭に FIXME や TODO をつけると、どのような問題を指摘しているのか、他の開発者がすぐに理解できるメリットがあります。

さらに VSCode では todo-tree などのプラグインを設定することでハイライトされ一覧で見ることが可能です。このアノテーションコメントを積極的に利用して、未実装の機能や対応しなければならないことの漏れを防ぐことができます。

以下に色々ありますが、個人的にはFIXME と TODO だけでだいたい大丈夫かと思います。

コメント	意味
FIXME:	既知の不具合あるコード。絶対に修正するという強い意志を感じる。
TODO:	やるべきこと。FIXME より弱い。実装するべき機能。
HACK:	リファクタリングしたい。要改善。
REVIEW:	見直しが必要である、または見てください。
WARNING:	注意してください。
NOTE:	実装の意図やなぜこう書いたかを強調するときに書く。

angular プロジェクトの README を参考にすると良いと思います。

Prefix	意味
build:	ビルドシステムや外部の依存関係に影響を与える変更（スコープ例：gulp、broccoli、npm)
ci:	CI 設定ファイルやスクリプトへの変更
docs:	ドキュメンテーションのみの変更
feat:	新しい機能
fix:	バグフィクス
perf:	パフォーマンスを向上させるためのコード変更
refactor:	バグフィックスでも機能追加でもないコード変更
style:	コードの意味に影響を与えない変更（空白、書式、セミコロンの欠落など）
test:	不足しているテストの追加や既存のテストの修正

Prefix	意味
feat:	新しい機能
fix:	バグフィクス
docs:	ドキュメンテーションのみの変更
style:	コードの意味に影響を与えない変更（空白、書式、セミコロンの欠落など）
refactor:	バグフィックスでも機能追加でもないコード変更
perf:	パフォーマンスを向上させるためのコード変更
test:	不足しているテストの追加や既存のテストの修正
chore:	ビルドプロセスやドキュメント生成などの補助ツールやライブラリの変更

以下のようなものも見受けられます。

絵文字をコミットメッセージのプレフィックスに使うこともできます。

gitmojiで絵文字と対応する意味をあらかた検索できます。
リポジトリを見た際に絵文字があるので可愛さが向上します。

以下の記事においては絵文字のテンプレートをつくりコミットの際に使用できるようです。
Emoji で楽しく綺麗なコミットを手に入れる

保守性の高いコードを書く手法はいろいろとあるかと思いますが、これらは簡単なことなので今後とも心がけたいですね。
プロジェクトに応じて使い分けするのが良いかと思います。