「コメント」は、ソースコードを読むだけでは分かりづらい情報を補足するのに役立つ。ただし書き方によっては、コメントはほとんど有益な情報を生み出さなくなってしまう。それはどのようなコメントなのか。
プログラミングにおいて良いコメントをソースコード内に残すことは、ソースコードの記述や修正の効率を向上させるために重要だ。良いコメントを書こうとするのであれば、まずは「悪いコメント」とはどのようなコメントなのかを理解するとよい。まずは「本来の役割を担えないコメント」とは何かを考えよう。
以下はプログラミング言語「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"})
上述のソースコードを簡単に説明すると、以下のようになる。
このソースコードの場合、ソースコードの処理の流れをそのままコメントとして書き写すことは悪手だ。ソースコードを読んだ人が関数やメソッド(データに対する処理)の意味を理解できるならば、それと同じ情報を伝えるコメントは意味がない。ソースコード内に存在する関数やメソッドの説明は、プログラミング言語の公式ドキュメントを参照してもらう方がより適切だ。
分かりやすくソースコードを説明するコメントがあったとしても、間違っていたり、古くなっていたりする場合がある。ソースコードに関わった人が同じようなコメントをどんどん書き足していくと、ソースコードが乱れて読みにくくなり、混乱や矛盾を招く恐れがある。
上述のソースコードにコメントを追加する場合、以下のようにするとよい。「#」で始まる行がコメントだ。
# 既存ユーザーであればログインを実行し、ユーザーが存在しなければ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の豊富な記事の中から、開発のノウハウや技術知識など、ITエンジニアの問題解決に役立つ情報を厳選してお届けします。
高齢男性はレジ待ちが苦手、女性は待たないためにアプリを活用――アイリッジ調査
実店舗を持つ企業が「アプリでどのようなユーザー体験を提供すべきか」を考えるヒントが...
IASがブランドセーフティーの計測を拡張 誤報に関するレポートを追加
IASは、ブランドセーフティーと適合性の計測ソリューションを拡張し、誤報とともに広告が...
【Googleが公式見解を発表】中古ドメインを絶対に使ってはいけない理由とは?
Googleが中古ドメインの不正利用を禁止を公式に発表しました。その理由や今後の対応につ...