現役エンジニアから直伝！コードへのコメントの方法とコツ
こんにちは！現役エンジニアの優輝です。
実は私は、2021年1月から渋谷のIT企業にてエンジニアとして働き始めました。
そこで、今回はエンジニアとしてプログラミングする際に重要な、コメントについて解説！
- プログラミングのコメントって何なの？
- 先輩エンジニアから直伝！コメントの書き方のコツ
職場では、JAVAというプログラミング言語をメインに書くエンジニアとして働いている私が先輩のベテランエンジニアから学んだコメントの方法を開設します。
プログラミングのコメントって何なの？
プログラミングにおけるコメントとは、プログラムが何をしているのかを分かりやすく日本語で解説を入れることです。
実はプログラムはコードを書くだけでは、動作はしてもどの箇所のコードがどんな動作をしてくれているのか？は理解がしずらいんですね。
ですが、コメントを書くことでどの場所のコードが何の動作をしているのか？を分かりやすくすることができます。
コメントはプログラムが何を分かりやすくできる
コメントでプログラムが分かりやすくなるのを、実際にお店しましょう。
例えば下記のようなJAVAコードは、どんな機能を発揮するコードかわかりますか？
public static void main(String args) {
System.out.printf("こんにちは");
}
このコードに意味がわかるようにコメントをすると以下の通りになります。
//画面にこんにちはを表示
public static void main(String args) {
System.out.printf("こんにちは");
}
そう、このコードは画面にこんにちは！と表示できるコードなんですね。
このように、コメントをすることで、英語の難しく見えるコードもどんな動きをするのかわかりやすくなります。
先輩エンジニアから直伝！コメントの書き方のコツ
- だれが読んでも分かりやすく
- １つの処理ごとに書く
- 修正メモはTODOを使おう
コメントは誰が読んでも分かりやすく
コメントはだれが読んでも分かりやすくするのが大切です。
難しい言葉や、記号のような意味のわかりずらいコメントは、自分意外のエンジニアが後からコードを見た時に意味が伝わりずらくなります。
なので、コメントは、分かりやすさを重視しましょう。
【良い例のコメント】
//画面にこんにちはを表示
public static void main(String args) {
System.out.printf("こんにちは");
}
【悪い例のコード】
//処理１を実行
public static void main(String args) {
System.out.printf("こんにちは");
}
※処理１ってなんやねんてなりますよね？誰が見ても分かりやすく書かないと後から見た人が混乱します。
１つの処理ごとに書く
コメントは１つの処理ごとに書くのが大切です。
処理ごとにコメントを書くことで、どんな機能や役割を果たしている場所なのか分かりやすくなります。
一方ですべてのコードにコメントをつけていくと、情報量が多すぎになるので注意が必要です。
修正する箇所はTODOを使おう
修正する箇所はTODOを使うことで、分かりやすくなります。
通常コメントは一度書いたら消さないことが多いのですが、メモ書きや修正箇所の目印としてコメントを付ける場合はTODOコメントを使います。
通常のコメントと違い、画面に記号が表示される上にTODOとはそもそもやる事の意味なので、修正箇所や新しく何かを書く場所なんだなという事が他のエンジニアに伝わりやすくなります。
【TODOコメントの付け方】
//TODO
上記のように//の後に大文字でTODOと書くことでTODOコメントになります。
実際に実用的な書き方をすると下記のようなイメージです。
//TODO 計算修正箇所
TODOと日本語のコメントの間には半角スペースをつけましょう。
