概要
この記事は、英語でコメントを書くためのTips集である。執筆にあたっては、英語ネイティブの間でライティング指南書の古典的定番とされている「The Elements of Style(William Strunk Jr./E.B.White)」(本文略：EoS)を参照しより良い英語を書く方法を検討する。
はじめに
コードに英語でコメントを残すとき、思考の流れを止めず(効率的)、第三者の理解に資するかたちで(明快に)記述することが求められるが、英語を母語としない非ネイティブにとってそれは困難な仕事だ。また、語学的なコンプレクスは、インターネットという本質的に言語的境界がない空間にさえパーテションを作る。その結果、手元に抱える素晴らしい成果物を外に向けて発信できなかったり、十分実力のある技術者が社会的価値のあるオープンソースプロジェクトへの参加を躊躇したりする。
学校教育で身につけた基本的な英語の知識をベースとしながら、自信を持ってコメントを書くためには、既存の知識に加えて一歩進んだライティングスキルが求められ、”よい英文”を書く作法というべきものを体系的に理解し型として身につける必要があると筆者は考える。
そこで、この記事では、1918年の出版以来、ネイティブの間で広く親しまれているスタイルガイド(文章作法のルール集)に則り、よりよい英文とは何かについてヒントを提示する。もちろん、Qiitaの想定読者はプログラマーであるから、IT技術者の目線から必要に応じて各ルールに簡単な解説を加える。
なお冒頭に記述の通り、この記事は英文の一般的なライティング作法を解説することを目的とし、コメントの一般的な作法は解説しない。つまり、"命名を工夫してコメントに残すな"、"どうではなくなぜを書け"、"コードとコメントの整合性を保て"などの約束事については言及しない。すでに偉大な先人の助言が多く明文化されており、私ごときがそれに付け加える必要性はないからだ。
「The Elements of Style(略：EoS)」の紹介
1918年、コーネル大学教授William Strunk Jr.が生徒に私的に配布したことで世に出たといわれるEoSは、その後、ジャーナリスト、研究者から一般市民まで万人向けのライティング指南書として、20世紀を代表する数々の名文の誕生を影で支えてきた。100ページに満たない非常に薄い本でありながら、個々のルールは実例付きで説得力のあるかたちで解説されており、いずれのルールも具体的かつ実践的である。
Amazonの書籍紹介
The Elements of Style is the definitive text and classic manual on the principles of English language read by millions of readers. The 18 main topics are organized under the headings, "Elementary Rules of Usage," "Elementary Principles of Composition," "A Few Matters of Form," "Words and Expressions Commonly Misused," and "Words Often Misspelled."
なお、訳本は長らく絶版になっており、高額で版も古いため洋書をKindle等で入手することをおすすめる。英文のマニュアルと日頃付き合う読者であれば、まったく問題なく読める内容である。
解説
さっそくEoS(4th Edition)からルールを紹介していこう。見出しの括弧内に典拠を示すので、できればEoS本文をご参照願いたい。
なお、大変恐縮だが筆者の時間の都合上、今回は生のプログラムのコメントを実例として紹介できなかった。いつか記述されるであろう実践編の記事において紹介したい。
語法についてのルール
Form the possessive singular of nouns by adding 's.[Ⅰ-1]
単数名詞の所有格には~'sを用いること
In a series of three or more terms with a single conjunction, use a comma after each term except the last.[Ⅰ-2]
三つ以上連続する語句を一つの接続詞でつなぐ場合、最後の一つを除き各語句の後にカンマを用いることEnclose parenthetic expressions between commas.[Ⅰ-3]
挿入句はカンマで囲むこと
文の流れを邪魔しない短い挿入語句であればカンマを省略することが認められる。ただし、一つだけ省略して片方を残すことは認められない。
その他、日付、非制限関係詞などにおけるカンマの用法については文法書を確認する。
Place a comma before a conjunction introducing an independent clause.[Ⅰ-4]
独立節を導く接続詞の前にはコンマを置くこと
〜, and ...や〜, but ...のような文のこと。
...は独立節で完全な文
Do not join independent clauses with a comma.[Ⅰ-5]
独立節をカンマでつながないことDo not break sentences in two.[Ⅰ-6]
文は二つに分けないことUse a colon after an independent clause to introduce a list of particulars, an appositive, an amplification, or an illustrative quotation.[Ⅰ-7]
リスト項目、同格語句、敷衍(言いかえや詳述)表現、説明的な引用を導く独立節の後にはコロンを使うこと。
〜 :A, B, C ...Use a dash to set off an abrupt break or interruption and to announce a long appositive or summary.[Ⅰ-8]
急な文の中断や割り込みが発生する場合や、長い同格表現や要約が出てくる場合にはダッシュを使うこと。The number of the subject determines the number of the verb.[Ⅰ-9]
主語の単複が動詞の単複を決める
単純なルールのようだが、Each of, One of, None ofのような名詞句が主語の場合には文法上のルールが存在するので要注意。
Use the proper case of pronoun.[Ⅰ-10]
名詞の格(主格・目的格・所有格)は適切なものを用いることA participial phrase at the beginning of a sentence must refer to the grammatical subject.[Ⅰ-11]
文頭の分詞構文は、文法上の主語を明らかにすること
特に〜(分詞構文), ...の二つの節で文法上の主語が違う場合には注意が必要。細かいルールは文法書で確認する。
文の構成についてのルール
Choose a suitable design and hold to it.[Ⅱ-12]
最適なデザインを選択したら、以後それを守り続けること
文体や構成などについての助言。
Make the paragraph the unit of composition.[Ⅱ-13]
パラグラフを構成単位として文章を書くこと
比較的長い文章については、読み手の理解のために1つのパラグラフに1つのトピックを置いて文章全体を構成するのが基本だが、コメントのような短い説明文の場合、無理にパラグラフを分割して書かなくてもよい。
Use the active voice.[Ⅱ-14]
能動態を使うこと
主語が不明確なるおそれがあるため一般的には、特殊な場合を除いて受動態は好まれないが、”ものの動作”についての記述が主である技術系の文書においては議論のあるところ。動作の主体をあえて明確に記述しない場合、受動態は重宝する場合がある。ただし、濫用は禁物である。
Put statements in positive form.[Ⅱ-15]
肯定形で記述すること
notやnoはあくまで、本来的な意味の否定のために用いるべきで、ためらいやあいまいさを表現するために否定形を用いるはやめる。このような表現には、多くの場合、肯定形の代替表現が存在する。
EoSでは例として以下のような文例が紹介されている。
not honest => dishonest
not important => trifling
Use definite, specific, concrete language.[Ⅱ-16]
限定的、明確そして具体的なことばを使うことOmit needless words.[Ⅱ-17]
不要な言葉は省略すること
EoSのルールの中でも最も引用されることが多いシンプルだがとても大事なルール。
Avoid a succession of loose sentences.[Ⅱ-18]
まとまりを欠く文章の連続避けること
文をやたらと短い節に分割して、and、butやwhileなどの接続詞で繋ぐような書き方は未熟なライターに多く見られる癖であると指摘している。コロンやダッシュなどのパンクチュエーションを効果的に使ったり、文節単位で構成を見直して読みやすい文に整えることが必要である。EoSには悪い例とよい例として二つの文が実例として紹介されているので参照のこと。
Express coordinate idea in similar form.[Ⅱ-19]
同等の考えは同じ形式を使って表現することKeep related words together.[Ⅱ-20]
関連する言葉は一緒に配置することIn summaries, keep to one tense.[Ⅱ-21]
概要や要約部では、ひとつの時制を使うことPlace the emphatic words of a sentence at the end.[Ⅱ-22]
強調する言葉は文の終わりに配置すること
文末のみならず文頭も意味上の強調語を置く場所として重要である。
文体についての手引き
Place yourself in the background.[Ⅴ-1]
筆者自身は黒幕となる
あくまで大事なのは文の実質的な意味であって、筆者自身の感情や情緒はあまり表に出すのは望ましくない。
Write in a way that comes naturally.[Ⅴ-2]
ありのまま自然に書くWork from a suitable design.[Ⅴ-3]
適切なデザインを探すことから着手するWrite with nouns and verbs.[Ⅴ-4]
名詞と動詞は一緒に書くRevise and rewrite.[Ⅴ-5]
改訂そして修正するDo not overwrite.[Ⅴ-6]
書きすぎない
過度に文学的な表現を用いて飾り立てることへの戒め。
Do not overstate.[Ⅴ-7]
大げさに書かない
最上級の表現をやたらに使ったり、必要以上に大げさに述べることへの戒め。
Avoid the use of qualifiers.[Ⅴ-8]
修飾語句を避ける
veryやlittleなど程度を表す副詞安易な濫用を戒めている。
Do not affect a breezy manner.[Ⅴ-9]
イキらない
中二病的な文章。EoSで興味深い文例が解説されている。
Use orthodox spelling.[Ⅴ-10]
オーソドックスなスペリングを使うDo not explain too much.[Ⅴ-11]
多くを説明しすぎない
具体的に書くなという意味ではない。必要最小限の言葉で簡潔明瞭に説明せよということ。
Do not construct awkward adverbs.[Ⅴ-12]
下手な副詞は使わない
overlyやmuchlyなど-ly形式の副詞を安易に使うのは混乱の元となるので注意が必要である。
Make sure the reader knows who is speaking.[Ⅴ-13]
(会話文において)読者が誰の発言か分かるようにするAvoid fancy words.[Ⅴ-14]
手の込んだのことばを避けるDo not use dialect unless your ear is good.[Ⅴ-15]
聴いて良いと思わない限り方言や派生語は使わない
定義の不明確な用語を使うと読者は違った意味に解釈する可能性がある。
Be clear.[Ⅴ-16]
とにかく明快にかくDo not inject opinion.[Ⅴ-17]
個人的な見解を挟まない
事実と書き手の意見の境があいまいになる点を問題視しての指摘である。プログラミングにおいては、判断の見解や個人的に知っているノウハウで、後で読んだ人が役立つことはコメントに残して共有するのが望ましい。
Use figures of speech sparingly.[Ⅴ-18]
比喩的な表現は控えめに用いるDo not take shortcuts at the cost of clarity.[Ⅴ-19]
明快さを犠牲にして略語を用いない
あまり一般的でない略語を使用する場合には、最初に何の略語か紹介する。
Avoid foreign languages.[Ⅴ-20]
外国語は極力使わないPrefer the standard to the offbeat.[Ⅴ-21]
とっぴな文より標準的な文を心がける
最後に
(以下駄文につき…)
英文でコメントはおそらく誰でも書けるはずだ。時間さえかけどんな文章でもよいとなれば。しかし、コーディングの思考のフローを妨げず(効率的に)、第三者が事後的に読みやすいかたちで(可読性を保って)書くことはネイティブであっても困難だろう。
正直に白状すると、こんな記事を書きながら私自身プロのテクニカルライターでもないし、どちらかといえば英語が得意でない。というより、苦手だからこんな勉強を始めた。なんだただの学習者か。残念ながらそうである。しかし、ここ最近、必要に迫られて自分で書いた日本語のコメントやドキュメントを全て英訳する必要があった。日本語で書いた膨大なドキュメントやコードを前にして途方にくれた。辞書を引き引き訳せど、あまりの遅速さと日々業務の傍ら目に触れるネイティブのドキュメントを前に自分の文章のあまりの拙さを嘆き自信を失った。ついつい、こんなことを考えタイピングは止まってしまうのだ。
この動作を解説するのに時制はどうすべきか？無生物主語で簡潔にすべきじゃないか？動名詞を使うべきかそれとも不定詞か？一文にまとめて書くべきなのか、関係詞を使うべきなのか？何度も登場する代名詞を省略すべきか？接続詞は書いた方がいいか？挿入句は入れてもいいか？助動詞の語調は適切か？もっと最適な動詞があるのじゃないか？
曲がりなりにも技術屋である私は、論理的に問題の分析にとりかかり始め、問題の根源は、(1)記述の効率性と(2)可読性の担保(それから羞恥心)にあるらしいこと。どちらもその解決には、型(パターン)を身に着けることが必要らしいことは目星がついた。
しかし、型とすべきよい模範とはいったいなにか？それを体系的に理解する必要があった。テクニカルライター向けの教本やIT企業のスタイルガイドを読み漁った。しかし、それでは上記のような問いに対して答えがでなかった。これらは、英語の一般的な文章に慣れ親しんだ読者を想定しるのだから当然である。そこで、手がかりとしたのはより手前の問題、ネイティブ自身が作文のマナーを身につける方法論だった。今度は、ライティングのHow-Toものを米Amazonで調べてベストセラーを数冊手に取った。多くの疑問が氷解した気がしたが、今度は読めば読むほど深みにはまり、ついにはそんな大きな問題はネイティブさえ手に負えない問題であらしいことを知り、「中学程度の文法でなんでもOK」という魅惑的な教義を掲げる団体に何度も入信しかけたことを白状する。
今になって思えば、もちろんやるべきは、必要最低限の知識を身につけて実践の中で反省を繰り返しながら少しずつ研鑽を積む他ない。プログラマーならごくごく自明のことだ。一方で、我々プログラマーには困った習性があるのも事実で、魔法の型を集めた収めたパターン集なるものの存在を信じ求めてやまない。性懲りも無く銀の弾丸を求める様は誠に愚かでありながら、見つからないとわかればそれに変わる技術を自ら作ってしまう実利主義的な行動原理は愛すべき性とさえいえる。
要するに、最低限のルールを覚えたらとにかく手を動かしていっぱい書く！そしてリファクタリングだ！
(見直せばごく単純なルールさえ守れていないことに気づくのだから、初めから抱えきれないルールなど無意味だ)
自分のこんな経験が、EoSを底本にしてこのような記事を書こうと思った動機にほかならない。この投稿をきっかけに英語でプロジェクトをマネジメントするノウハウの共有が広がることを期待したい。
参考情報
その他テクニカルライティングというジャンルに縛られず、英文の一般的なライティングスキル向上に役立つと思われる情報を紹介する。(文法書は除外)
なお、この他洋邦問わず膨大にある類書のなかから、技術者にとって有益だと思われるものがあれば、コメント欄からご紹介をお願いしたい。その際、どんなところが役立ったか一言加えてくだされば幸いである。
技術系英文ライティング教本(中山 裕木子)
技術系ライター向けの教本の中でも定評のある本。3Cといったテクニカルﾗｲﾃｨﾝｸﾞの基本的な作法に始まり、文法上の落とし穴や訳し方などについて豊富な実例と練習問題と併せて記述されておりとても実用的。技術系ライターに必要な基礎知識はこの一冊で十分カバーできるはず。
The Handbook of Technical Writing(Gerald J. Alred/ Charles T. Brusaw/Walter E. Oliu)
既に11版まで版を重ね、テクニカルライター必携のハンドブックとしてネイティブの間で定番の書籍のようである。スタイルガイドにとどまらず、用語や文法などハマりどころを徹底的に解説している。必要な事項はほぼ網羅されており、リファレンスとして備えるのであればこの一冊。
Writing Tools(Roy Peter Clark)
ジャーナリストや作家として長年活躍し、現在ピューリツァー賞の選考委員も務める著者。新聞記事のコラムから古典文学、果ては詩まで範を求め、EoSの信奉者を公言する筆者が選りすぐりの珠玉の名文を、現代のライターに向けて50(改訂版で+5)のツールに昇華する。とにかく例文のジャンルの守備範囲の広さと分析の切れ味がすごく、著者自身がなにより身近な一流の物書きへの徹底したヒアリングの成果と語る通り、広く文章の達人に共有される暗黙知が明文化されている。主語と動詞はくっつけるべきか？受動態はいつ使うか？長い文章は本当にダメなのか？句読法の効果的な用い方は？等ネイティブ間でも論争の種となる難題にも珠玉の名文を引用しながら論理的に答えていく。
A Plain English Handbook(SEC)
https://www.sec.gov/pdf/handbook.pdf
Plain Englishは、主に専門家でない不特定多数の読者に公共性の高い情報を開示する場合に、簡潔でわかりやすい英文を推奨した広義のスタイルガイドだ。本文書は米国の証券取引委員会(SEC)が、大企業向けが投資家向けに公開するIR情報の作成指針を記したハンドブックであり、Plain Englishの要点が、実例豊富な実例付きで簡潔にまとまっている。特にAppendix2の実例からは技術者といえど学ぶ点が多いはず。
Writing Better English(Robert Allen)
発行元は英国の大手出版社。著者はOxford English Dictionaryの編集者や英文法書の最重要書の一つFowler's Modern English Usageの抄書版の編集責任者を歴任したグラマーの大家。英作文で落とし穴になる文法事項を網羅的におさらいしながら、英国人らしく(?)より正しい文章を書く上で文法の理解がいかに大切であることを再認識させてくれる本。例文として選定された文章も秀逸。
On Writing Well(William Zinsser)
EoSと並び米国で定番の古典の一つとしてライティング作法を紹介した書籍として広く読まれている。EoSが情報伝達を主眼とした文章一般を論じているのに対し、ナラティブを含むストーリー性の高い形式でのライティングについても言及されている。中には少し古びた助言も見受けられるが、簡潔にまとめられた要点はどれも普遍性があり実践的。その後に出版されたこの手の指南書の類は結局単なる焼き直しではないかとさえ思わされる。
IT企業によるスタイルガイド(MicroSoft,Apple,IBMほか)
IT技術者向けに書かれており、何より記述にがあるため、特に複数人の関わるプロジェクトでドキュメントの一貫性を担保する意味で大いに参考にすべき情報である。ただスタイルガイドを参考にその場からすぐにコメントの記述に必要な英文が書けるわけではない。英語がある程度書ける人向けに狭い専門分野の中での文章作法である。遠回りかもしれないが、非ネイティブとしてはまずはEoSでライティングスキルの土台を築くのがよいと思う。
The Chicago Manual of Style(University of Chicago Press)
主に学術論文の執筆者向けに記述されたスタイルガイド。アカデミックの世界にいた方なら名前くらいは知っているかもしれない。古典ながら論文向けのスタイルガイドとしては今も絶大な影響力を持つ(Code Complete的存在)。しかし、EoSに比べてとにかくページ数(約千ページ)が多く高価(約7千円)、個人的にはプログラマー向けの情報として少々過剰な気がする。そもそも、論理の立証や引用の作法という側面に関心があるため、システムの挙動や使い方の記述が主であるプログラマー向けの文章とは内容が必ずしも合致しない。もちろん一般的なライティングを学ぶ上で重要なアドバイスが多く紹介されている。リファレンスとしても使える。筆者は図書館でたまに参照する。