「コードに直訳コメント不要」は糞コードや日本人プログラマーの英語力を甘く見てる
ここで要るか要らないかと言われてるのは所謂「直訳コメント」という奴で、コードとほぼ一対一になるような奴。
「どこまでを直訳コメントと呼ぶか?」については、まとめでも意見が分かれてるが、上げられてるサンプルが
// 猫の身長に入力データを設定するなので、(メソッド名などから推測可能なレベルで)処理内容を示すようなコメントを、以下直訳コメントとして扱う。
$cat->setHeigth($inputData);
で、つぶやいた通り、私は基本的に「コメントたくさん書くべき派」です。
詳細なコメントなら当然として、直訳コメントについても、↑のレベルなら出来るだけ書くべきだと思ってます。
が、まとめだと「メソッド名とかでわかるからコメント不要」って言っている人が多い気がしたので、糞コードメンテ歴12年の俺から、それ絶対「糞コードや日本人プログラマーの英語力を甘く見てるわ」という話を書かせてもらいます。
以下は、最近触ってる実在のプロジェクトのソースを、プライバシーとか守秘義務とかに配慮した感じに簡略化した糞コードです。
(便宜上FuelPHP 1.8で作成。実物は違うのでFuelPHPでそれはおかしいとかは勘弁(--;)
なお、このプロジェクトには「直訳コメントは書くな、メソッド名などをちゃんとしてコメント無しでも分かるコードを書け」というコーディング規約が存在しています。
use \Model\Present;はい、まあ分かりやすいシンプルなコードですね。
class Controller_Present extends Controller {
public function action_get_present($id) {
$data = [];
$data['result'] = Present::get_present($id);
return View::forge('get_present', $data);
}
}
ぱっと見た感じで、処理内容が「プレゼントを取ってきて、それを画面に表示する」であることは一目瞭然です。
これなら、もちろん直訳コメントなんて要りませんね!
(個人的には、アクション名とかビュー名とか良くないと感じますが…まあ意味は通じるという観点で。)
が、実際にこのメソッドがやっていることは違います。Present::get_present($id) の中身を見てみましょう。
namespace Model;Σ (゚Д゚;) そうです。このアクションは「プレゼントを受け取る」機能だったのです(怖
class Present extends \Model_Crud {
public static function get_present($id) {
$data = [];
$data['user_id'] = $_SESSION['user_id'];
$data['present_id'] = $id;
$present = Present::forge();
$present->set($data);
return $present->save();
}
}
社内でも古いソースのようで、誰が書いたのかは定かではありませんが(ただしコピペされてたまに増える)、おそらくこのコードを書いたプログラマーは、「ユーザーがプレゼントをGETする処理だからget_presentだ」と思ってこのメソッドを設計したのでしょう…getという単語が他のプログラマーにどう認識されるかを考えないままに…。
このコードは、直訳コメント以前にそもそも糞コードであり、モデル内でセッションを見ていたりとツッコミどころはいくらでもあるのですが、少なくとも、直訳コメントがあればアクションを見ただけで異常に気付くことができました。
use \Model\Present;(上の例だと、直訳コメント以前にphpdocコメント書けって話になりますが、実際はもっと長いコードの途中に突然これが出てきます。っていうか、本当は直訳じゃなくて「// ユーザーに指定されたプレゼントを付与する」レベルで書いて欲しい。)
class Controller_Present extends Controller {
public function action_get_present($id) {
$data = [];
// プレゼントを受け取る
$data['result'] = Present::get_present($id);
return View::forge('get_present', $data);
}
}
上は特に酷い例を抜き出していますが、ここまで酷くなくても、「英語のつもり」のメソッド名が、何を意味しているのか分からないことは日常茶飯事です。
逆に、メソッド名で意図が分かるコードを書いても、こういうのを書くプログラマーに正しく意図が通じるとは到底思えません。
読み手書き手ともに、英語ペラペラです、という特異な環境でない限りは、日本人プログラマーはちゃんと日本語のコメントも残しましょう、というお話でした。
PS. まあ糞コード書く人は、コメントも意味わからん糞コメント書くんですけどね…(虚ろ目