海外IT企業で働いていた純日本人エンジニアがいろいろと考えてみる。

「みんなのIT英語」その2

»

 どうも、鹿島和郎(かしまかずお)です。

 今回も引き続き「IT英語」に関して書こうと思います。さて、今回のネタは「コメント」です。FFで隕石が降ってくる魔法のことです。最近、エンジニアライフではドラクエをネタにしたコラムが人気のようですので、張り合ってみました。

■英語のコメントが分かりにくい

 以前関わっていたプロジェクトでは、ソースコードのコメントが英語でした。細かい間違いがあるのは別に構わないのですが、意味を理解するのに時間がかかるコメントがあり、「コメントを読まずにソースを直接読んだ方が早い」という本末転倒な状況がしばしば起こっていました。

 さて、そのプロジェクトのコメントを読んでいたところ、分かりにくいコメントにはいくつかの傾向があることに気付きました。今回、それら問題があるコメントの傾向、及びそれらへの対策についていくつか述べていきます。

■傾向1:和英を使ってそれでおしまい

 「和英を使っておしまい」。これは、英語のコメントを書く際に、和英辞書で引いて出てきた単語を意味をよく調べずにそのまま使うということです。

 まったく架空の例ですが、「受け取ったデータを一時的にファイルに退避する」という文があったとします。

 ここで「退避」を辞書で引いて、evacuate なんて単語を使ってしまうと、アウトです。

○対策 1-a. 和英で引く→英和で意味を再確認

 そもそもevacuateの意味って知っていますか。実際に使う前に、もう一度「evacuate」で辞書を引いてみると、「あれ? 何か違うな」と気付くと思います。

 和英で調べた単語(この例ではevacuate)の意味がよく分からないのなら、もう一度英和を引くことを強く推奨します。

○対策 1-b. 簡単な単語を使う

 もう1つお勧めしたいのは、「難しい単語は使わずに簡単な単語で言い換えられないかを考えてみること」です。難しい単語というのは、えてして限定した文脈でしか使えなかったりします。

 先の例ですと、「ファイルに退避する」ではなくて、「ファイルに保存する」に言い換えてみると、save って単語が思い浮かぶ方も多いと思います。

 別の例ですが、「値を取得する」を「acquire a value」と訳しているコメントを見たことがありますが、これは(意味がまったく通じないことはありませんが)かなり変です。ここでは普通に「get a value」とするべきです。

 acquireもgetもどちらも何かを「得る」という意味がありますが、getが広い意味で使われるのに対して、acquireはもっと限定された意味でしか使われません。

 動詞に関して言うと、get、set、take、put、have、go、send、receive、save、loadなどなど、そうした簡単な単語だけで99%はOKだと思います。

■傾向2 名詞を並べる

 日本語のコメントでは、以下のように名詞形でのコメントが多いと思います。

// レコード全件削除処理

 これと同じ感覚で、英語でも

// all record deletion

のように書いているコメントもよく見かけますが、これも不自然です。

○対策2 動詞を使う

 英語のコメントでは、その処理が何をするのかという「動詞」であらわすことが多いです。先の例で言えば

// Delete all the records.

と書く方が自然です。主語は「This block」、「This line」などコメント対象となっているコードですが、あえて書かなくても分かるため普通は省略します。

 あと、海外のオープンソースソフトを見てみると気付くかもしれませんが、下の例ですと(1)では動詞に三単現の"s"を付けるのですが、(2)の場所では付けないことが多いようです。

/**
* Inserts a record to the user table. → (1)
*/
public void insertRecord(Record record) {
  // Check the parameter → (2)
  :
  :
}

#文法的になぜそうなってるのかは……よく分かりません。すみません。

■まとめ

 ちょっとしたコツをつかむだけで、格段に分かりやすい英文コメントを書けるようになると思います。コツは、ここに書いた以外にもいろいろとあると思います。そして、そうした勘所をつかむのに一番いいのは、本文中でも少し触れた「オープンソースのソフトのコードを読む」ではないかと思います。

 それではまた次回。

Comment(8)

コメント

ごんべえ

(1)の主語はthis functionが省略されている。
(2)の主語はWe or Iが省略されていて、this line/blockの省略ではない。
ということでいいんじゃないでしょうか。

鹿島

ごんべえさん、初めまして。

(1)はその通りですね。
(2)に関してはちょっと分かりません。仰る通りWe か I なのかもしれません。

いずれにしても、実際に仕事をする時にはその辺は気にせずに無意識でsを付けたり付けなかったりしてます。

はがねのつるぎ

はがねのつるぎです。

さりげなく、ご紹介していただき、ありがとうございます。

わたしもエラーメッセージで名詞の羅列を英単語に置き換えただけという
同じような失敗をやらかした経験があるので耳が痛いです(^^;

ずっと処理=コンピュータへの命令だからコメントも命令文だと思っていました(^^;

鹿島

はがねのつるぎさん、こんにちは。

コメントありがとうございます。

「名詞の羅列」は結構みんなやってしまうんですね。こんなコラムを書いておきながら、「これって自分の関わっていたプロジェクトだけの話だったらどうしよう」とかちょっと思ってたのでホッと(?)しました。

命令文、なのかもしれません。私にとってやっぱり英語は外国語なので、こういう細かいニュアンスとかがよく分からないんですよね。

ところで、ドラクエに欠かせないネタっていくつかありますが、それをOOPとどうやって絡めるのかに興味があります。転職とか伝説の武器防具とかぱふぱふとか。

naomsa02

naomsa02 です。

ネイティブ視点になりますが、コメントを書いている人がネイティブじゃない時は、名刺の羅列の方が読みやすいです。

なぜなら、接続詞やらを多様されると本当に何が言いたいのかが分からなくなってしまうためです。動詞も利用が間違っていることが多いのを見られるので、省かれている方が、個人的には理解しやすいです。直感的に何が言いたいのかを理解するためには、名詞だけの方が。。

(2) はもう、人それぞれな気が。。個人的には s を入れる時とそうでない時がある気がします。。簡単に言ってしまうと、どちらでも意味が通るからです。

鹿島

naomsa02さん、こんにちは。

ネイティブ視点からの貴重なコメントありがとうございます。

> 接続詞やらを多様されると本当に何が言いたいのかが分からなくなってしまうためです。

これは仰るとおりで、簡潔な文章で書くことは重要だと思います。英語だけでなく日本語でのコメントや仕様書にも言えることですが。

> 動詞も利用が間違っていることが多いのを見られるので、省かれている方が、個人的には理解しやすいです。

これは何となく分かるんですが、その間違った動詞の名詞形が変な場所で使われてると余計分かりにくいかなぁと私は思います。

この辺は人によって感覚が違うのかもしれませんね。

(2)に関して、ご説明ありがとうございます。

はじめまして。いつも読ませていただいております。

揚げ足取りで申し訳ないのですが、
>今回のネタは「コメント」です。FFで隕石が降ってくる魔法のことです
この部分が少しひっかかりました。

FFで隕石が降ってくる魔法=コメント

という読み方なのであれば、コメントではなくコメットの間違い・・・?ともやもやしてます。
くだらないですが、回答いただけると幸いです。

鹿島

?さん。はじめまして。

いつも読んでいただきありがとうございます。

はい。ご指摘の通り実際は「コメット」ですね。(英単語のcometが由来?)
単にドラクエのコラムを紹介するために、コメント→コメット→FF→DQという風に持って行きたかっただけの、苦し紛れの言葉遊びという事でご容赦ください。

それでは。

コメントを投稿する