--
--

スポンサーサイト

上記の広告は1ヶ月以上更新のないブログに表示されています。
新しい記事を書く事で広告が消せます。

Tag:

05
2015

「コードに直訳コメント不要」は糞コードや日本人プログラマーの英語力を甘く見てる

CATEGORYPHP
Twitterでも言及したけど、今週話題になった「コードを直訳したコメントは必要なのか?「要る派」と「要らない派のまとめ」【 社畜ちゃん台詞メーカー 】 」を見てちょっと思うところがあったので書いてみる。

ここで要るか要らないかと言われてるのは所謂「直訳コメント」という奴で、コードとほぼ一対一になるような奴。
「どこまでを直訳コメントと呼ぶか?」については、まとめでも意見が分かれてるが、上げられてるサンプルが
// 猫の身長に入力データを設定する
$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;
class Controller_Present extends Controller {
public function action_get_present($id) {
$data = [];
// プレゼントを受け取る
$data['result'] = Present::get_present($id);
return View::forge('get_present', $data);
}
}
(上の例だと、直訳コメント以前にphpdocコメント書けって話になりますが、実際はもっと長いコードの途中に突然これが出てきます。っていうか、本当は直訳じゃなくて「// ユーザーに指定されたプレゼントを付与する」レベルで書いて欲しい。)


上は特に酷い例を抜き出していますが、ここまで酷くなくても、「英語のつもり」のメソッド名が、何を意味しているのか分からないことは日常茶飯事です。
逆に、メソッド名で意図が分かるコードを書いても、こういうのを書くプログラマーに正しく意図が通じるとは到底思えません。

読み手書き手ともに、英語ペラペラです、という特異な環境でない限りは、日本人プログラマーはちゃんと日本語のコメントも残しましょう、というお話でした。

PS. まあ糞コード書く人は、コメントも意味わからん糞コメント書くんですけどね…(虚ろ目
スポンサーサイト

Tag: プログラミング

2 Comments

wa  

No title

英語力が低い事への懸念は他にも有って、
「現在」の present と混同されてしまう事を避けて
私は Gift オブジェクトと付けますね。

2015/12/12 (Sat) 02:54 | EDIT | REPLY |   

honeplus  

No title

ですねぇ、その辺の単語の選び方にもプログラマーの工夫が光るところです。
意味が多い単語や、かといってあまりにも一般的でない単語も困りどころ。。。

2015/12/12 (Sat) 09:55 | EDIT | REPLY |   

Leave a comment

上記広告は1ヶ月以上更新のないブログに表示されています。新しい記事を書くことで広告を消せます。