はじめに
こんにちは、IT経験1年半の駆け出しです。
今回は、開発現場で使われている「コメントアウト」の種類と使い方についてお話しします。
初めて現場に参画した時コードに説明コメントが書かれていて驚いたことを覚えています。
研修でコードを書いていた時にはコメントを書くということを一切したことがなかったので...
特に /** */ というコメントアウトを見た時には、こんなコメントアウトがあるのか、他のコメントアウトと何が違うんだ？と思ったのを覚えています。
コメントアウトの種類と使い方
現場では主に以下の3種類のコメントアウトが使われます。
| コメント形式 | 用途 |
|---|---|
// |
行コメント（1行のみ） |
/* */ |
ブロックコメント（複数行） |
/** */ |
JSDocコメント（関数の説明） |
-
//行コメント
1行の処理に対して、簡単な補足をつけるときに使用します。
以下、例です。
// 名前を入れる変数
const name = "太郎"
-
/* */ブロックコメント
複数行に渡ってコメントを書きたいときに使います。
ただしこれはあくまでコードの一時無効化やメモとして使うことが多く、関数の説明にはあまり使いません。
以下、例です。
/*
この処理は現在使用していません。
後で削除予定。
*/
-
/** */JSDocコメント
関数や変数の説明に使用される正式なドキュメンテーションコメントです。
関数の上に書いておくと、マウスホバーや補完時に説明が表示されるので、チーム開発でとても重宝されます。
/**
* 説明文
* @タグ（補足情報）
*/
以下、例です。
/**
* 名前を表示する
*/
function sayName() {
console.log("たろう");
}
sayName();
sayName()にカーソルを合わせると以下の画像の赤枠のように、コメントアウトの内容が表示されます。
タグの使い方の例です。現場では以下のような使い方をしているところが多かったです。
/**
* 数値を2倍にする
* @param num 数値
* @returns 2倍の数値
* @example
* double(3); // 6
*/
function double(num: number): number {
return num * 2;
}
よく使うコメントアウトは
説明コメントを書くときのコメントアウトには/** */をよく使います。
先ほど少し触れた部分もありますが以下の理由です。
- 補完される
VSCodeなどで関数名にカーソル名を合わせると説明が表示される - ドキュメントになる
JSDocというツールでドキュメントになる - チーム開発で便利
他の人がコードの意味をすぐ理解できる - 型・引数の説明ができる
@param@returnsなどで明確に書ける
おわりに
最初はコメントの書き方なんて気にしていなかった私ですが、現場に入ってその大切さを痛感しました。
コードは「書く」だけではなく「読まれるもの」。だからこそコメントも立派な開発の一部です。
「コメントの書き方なんて習っていない」という方もまずは/** */を使って一言補足から使ってみてください。