LoginSignup
0
3

More than 1 year has passed since last update.

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

Posted at

どんな内容か

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

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

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

JSDoc

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

/**
 * 足し算するやつ
 * @param a 1つめの数値
 * @param b 2つめの数値
 * @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;
}

定数はコメントがあると助かる

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

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

よりシングルラインを強調したいときはアノテーションコメント

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

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

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

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

コミットコメントの Prefix について

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

angular Commit Message Guidelines

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

angular.js

Commit Message Format

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

他には

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

参考: Git のコミットメッセージの書き方

Prefix 意味
update: 機能修正(バグではない)
add: 新規(ファイル)機能追加
remove: 削除(ファイル)
merge: マージコミット

emoji prefix

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

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

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

最後に

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

参考文献

Airbnb JavaScript Style Guide

0
3
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
0
3