【プログラミング初心者必見】ソースコードお作法

　こんにちは〜インフラエンジニアのtamolabです！今回はソースコードのお作法についていくつか紹介したいと思います。
　お作法にはいろいろあるのですが、今回はコメントアウトお作法について記載していきます！コメントアウトの記載方法は言語によって異なりますので、本記事ではシェルスクリプトを題材にしています。お作法自体は他の言語でも活用できるかと思います！本お作法はあくまでローカルルールになります。各組織の方針や自己流のやり方があるかと思いますので、あくまで参考までにしていただければと思います。

1. コメントアウトとは

　コメントアウトはソースコード上に書かれているメモのことです。コメントアウトされている部分はプログラムに影響しません。用途としてはいくつかありますが、代表的な用途は下記になります。

・ソースコードにメモを残す
・デバッグに利用する

プログラムのデバッグをするときに、元の記載を消さずにまるっとコメントアウトして無効化することでデバッグの時間を大幅に節約できます。　

　また、ソースコードは他の人が見ることを前提に作るので、他の人が見て理解してくれるようなコメントアウトが求められます。

2. ヘッダーを書こう

　これは私流なのですが、ソースコードにヘッダを書きましょう。ヘッダ の例は下記になります。シェルスクリプトなので、各行に対して、”#”以降の文字はコメントアウトとして扱われます。全て先頭に#が付与されているので、プログラムには一切関与しませんが、人間が見てどのようなファイルかがわかるようなコメントアウトになります。

##########
#Title:		　　  XXXXスクリプト
#Copyright:	　　  XXXXX Corporation
#Created By: 　　 Name Name
#Script Name:	 test-commnet.sh
#Updated Date:	 2021/02/27
#Version:        1.0.0 
#etc:		     XXXXXXXXXXX
##########

3. 関数を使うときは役割を簡潔に書こう

　関数を定義するときは、この関数は何をするのかを簡潔に書きましょう。下記方は下記のような体裁をお勧めします。すごく見やすいです。思い切って、#で文字を囲んでしまいます。

#############################
## データの重複確認を行う関数 ##
############################
function ....
　　　　
###########################
## エラーメールを送信する関数 ##
###########################
function ...

4. 乱用はやめよう

　あまりコメントアウトを書きすぎるとうっとしくなるので、簡潔に描きましょう。例えば下記のような例を見てみましょう。

(例1)
# ログファイルにリダイレクトします。
echo "UPDATE LOG FILE " >> /var/log/test.log

(例2)
​# 変数HENSUUを初期化
HENSUU=""

これらは不要なコメントアウトかと思います。個人の自由ではありますが、「なぜこのような処理をしたのか」については記載することをお勧めします。「変数HENSUUを初期化」ではなく、「XXXXのため変数HENSUUを初期化」という感じです。WHYを意識したコメントアウトを使うことで誰が見ても見やすくなると思います。ただし、長文はNGです笑

5. キーワード

#シェルスクリプト #IT #コメントアウト #インフラエンジニア #ネットワークエンジニア #プログラミング #初心者

6. お問い合わせ

　本投稿のコメントでも構いませんし、下記からお問い合わせいただいても大丈夫です。
　note.tamolab@gmail.com