Pythonのソースコードで考える「こんなコメントは無駄なだけで無意味」：プログラマーが知るべき「良いコメント」の条件【第2回】

「コメント」は、ソースコードを読むだけでは分かりづらい情報を補足するのに役立つ。ただし書き方によっては、コメントはほとんど有益な情報を生み出さなくなってしまう。それはどのようなコメントなのか。

[Matthew Grasberger，TechTarget]

　プログラミングにおいて良いコメントをソースコード内に残すことは、ソースコードの記述や修正の効率を向上させるために重要だ。良いコメントを書こうとするのであれば、まずは「悪いコメント」とはどのようなコメントなのかを理解するとよい。まずは「本来の役割を担えないコメント」とは何かを考えよう。

こんなコメントは「無駄なだけで無意味」

併せて読みたいお薦め記事

連載：プログラマーが知るべき「良いコメント」の条件

• 第1回：「コメント」の“本当の意味”を誤解していないか？

ソースコードの書き方

• 「Python」と「Go」のソースコードを比べて分かる「インデント」の違いとは？
• 命令型プログラミングと宣言型プログラミングの「ソースコード」の違いとは？

　以下はプログラミング言語「Python」で実装した、Webアプリケーションのログイン機能の例だ。Webアプリケーションを実装するためのフレームワーク（特定の設計思想を具現化するプログラム部品やドキュメントの集合体）「Flask」を利用している。

@app.route('/login', methods=['POST'])
def login():
   info = json.loads(request.data)
   username = info.get('username')
   password = info.get('password')
   user = User.objects(name=username, password=password).first()
   
   if user:
       login_user(user)
       return jsonify(user.to_json())
   else:
       return jsonify({"status": 401,
                       "reason": "Username or Password Error"})

　上述のソースコードを簡単に説明すると、以下のようになる。

• 1行目
  • Webアプリケーション内のログインURL（「/login」）でPOSTメソッド（サーバへのデータ送信要求）を実行した際に、2行目以降で定義する関数を呼び出すことを示す。POSTメソッドで受け取ったJSON形式のデータを変数「request.data」に格納する。
• 2行目
  • 関数の名前を「login」と定義する。
• 3行目
  • 受け取ったデータ（request.data）を変数「info」に代入する。
• 4行目
  • info中にあるユーザー名（username）のデータを変数「username」に代入する。
• 5行目
  • info中にあるパスワード（password）のデータを変数「password」に代入する。
• 6行目
  • データベースから、usernameとpasswordが一致する最初のレコード（データの組）を参照し、該当するレコード（ユーザーデータ）を変数「user」に代入する。
• 8行目
  • ユーザーが存在するかどうか（userにデータが代入されているかどうか）を確認する。
• 9行目
  • （ユーザーが存在する場合）Flaskの拡張機能群「Flask-Login」の関数「login_user」でログイン処理をする。
• 10行目
  • （ユーザーが存在する場合）userが保持するデータをJSON形式にしてから、HTTP通信用のデータに加工し、呼び出し元に渡す。
• 12、13行目
  • （ユーザーが存在しない場合）JSON形式のエラーメッセージを、呼び出し元に渡す。

　このソースコードの場合、ソースコードの処理の流れをそのままコメントとして書き写すことは悪手だ。ソースコードを読んだ人が関数やメソッド（データに対する処理）の意味を理解できるならば、それと同じ情報を伝えるコメントは意味がない。ソースコード内に存在する関数やメソッドの説明は、プログラミング言語の公式ドキュメントを参照してもらう方がより適切だ。

　分かりやすくソースコードを説明するコメントがあったとしても、間違っていたり、古くなっていたりする場合がある。ソースコードに関わった人が同じようなコメントをどんどん書き足していくと、ソースコードが乱れて読みにくくなり、混乱や矛盾を招く恐れがある。

　上述のソースコードにコメントを追加する場合、以下のようにするとよい。「#」で始まる行がコメントだ。

# 既存ユーザーであればログインを実行し、ユーザーが存在しなければ401エラーを返す
@app.route('/login', methods=['POST'])
def login():
   info = json.loads(request.data)
   username = info.get('username')
   password = info.get('password')
   # データベースから、入力されたユーザー名とパスワードに一致するユーザー情報を取得する
   user = User.objects(name=username, password=password).first()
   
   if user:
       login_user(user)
       return jsonify(user.to_json())
   else:
       return jsonify({"status": 401,
                       "reason": "Username or Password Error"})

---

　次回は、良いコメントとはどのようなものかを考える。

TechTarget発　エンジニア虎の巻

米国TechTargetの豊富な記事の中から、開発のノウハウや技術知識など、ITエンジニアの問題解決に役立つ情報を厳選してお届けします。