私はウンザリしています。

「○○対応」は曖昧なのでやめてください。「○○を修正した」の方が直接的です。

こんな指摘を新人が入ってくるたびにコードレビューやドキュメントレビューで繰り返しています。どうも、プログラマー（と言うか理系？）には独特の言語文化があり、みんな同じような分かりにくい表現をしてしまうようです。

「レビューを依頼する前にこれを読んどいて！」と言える記事なり本なりがあれば良かったのですが、良いものが見つけられなかった（ご存知なら教えてください）ので、とりあえずレビューでよく指摘する日本語の文章の問題点や変な表現ポイントを列挙しました。

なお「コメントは必要十分な量を書く」「チケット番号やWikiのURLを書く」といった、良く知られた・日本語に限定されない話題は省略しています。

（※コメント欄などの指摘を受け「補足」を追加）

（※タイトル変更。「コードレビュー前に直して欲しい日本語コメントの問題点８つ」でしたが、コードコメントに限定した話ではなく、むしろドキュメントなどで問題になりやすい事柄なので、変更しました。）

1. 俗称を使わない・造語しない

製品名・機能名などは正式なものを使いましょう。大抵はUIなりマニュアルなどで使われている名前が正式です。

正式な名前がわからなくなっている事もあります。開発者と利用者で呼び方が違うなど（レガシーシステムでありがち）。その場合も勝手にどちらかを選ぶのではなく、チーム内でルールを決めてください。

2. 方言・業界用語を使わない

どの出身地・世代でも伝わる言葉を選びましょう。

さすがに「ファイルを開ぐのがいずいっちゃ」等のモロな方言を見たことはありませんが、首都圏方言や若者言葉は時々見かけます。

例えば、

「listよりsetのが高速です」

は、地方の年配の人は脱字（「〜の方が〜」の「方」が抜けている）と思うでしょう¹。

また、工学科・情報科の中でしか通じない言葉も見逃されがちです。例えば：

知見が得られた
エビデンスが無い

これらは、一般的な言い方に直しましょう。

NG 知見が得られた
OK 〜であることが分かった

NG エビデンスが無い
OK 科学的に証明はされていない
OK Excelファイルにスクリーンショットの画像が添付されていない

また、SE用語（不思議の国のSE用語）はSE以外の人が読む可能性がないか注意して使ってください。

3. 助動詞を使う（体言止めをしない）

助動詞を省略すると、時制・完了・必然性などが曖昧になります。例えば「メールを配信」は文脈により、以下の意味になることがあります:

「メールを配信しなければならない」
「メールを配信した方がよい」
「メールを配信してもよい」
「これからメールを配信する予定だ」
「メールを配信した」

もちろん文脈から推測できることが大半ですが、読み手の負荷を軽くするために、語尾（助動詞）をはっきり書きましょう。

特に

「〜してもよい」（may）
「〜するべきである」(should)
「〜しなければならない」(must)

この３つについてはRFC2119で規定されているくらいですから、はっきり書きましょう。

4. 「〜が必要です」を使わない

このツールを使うには Python 3.7 が必要です。

読み手にとっては「必要です」では情報が不十分で、以下のように思案することになります。

Python 3.7 をインストールするにはどうすればいいのか？
必要だとして、今すぐPython 3.7 をインストールするべきなのか？このドキュメントを全て読んでからインストールするべきなのか？
もし Python 3.7 をインストールできない場合はどうすればいいのか？

何かが必要なら、明示的に指示した方が、読み手を迷わせません。また、手順書などへのリンクを置くと、なお親切でしょう。

このツールを使う前に Python 3.7 をインストールしてください。
インストール方法はこちら → http://example.com

5. 「つまり」「要するに」「端的に言うと」「簡単に言うと」「結論から言うと」などは削除する

単に削除しましょう。

これらの定型句は情報を増しません。口語での「ええっと」「その〜」などと同じ、心のうめきに過ぎないからです。

これらを使いたい・思わず使ってしまう人は、自分の文章を見直してください。「端的に言うと」「簡単に言うと」「結論から言うと」と書いている文章は、後続する文が端的にも、簡単にも、結論から言っているわけでもないことが、実際には（なぜか）多いからです。

6. 「○○対応」を使わない

例えばこんなコメントです：

# チケット#143567の不具合対応
# SPA化対応

「〜対応」をつけると、なんだかそれっぽい雰囲気になります。でも、「〜対応」を付けたからといって、情報量が増えるわけでも、わかりやすくなるわけでもありません。

「〜対応」は単に削除しましょう。あるいは、単語で済ませず本来書くべき説明を書きましょう。

「対応」を単に削除
# チケット#143567の不具合
# SPA化

丁寧に書く
# 未ログイン時に表示が崩れる不具合を回避するためのハック（チケット#143567）
# SPA化のために、外部向けAPIと同様の物を別立てで実装している

7. 箇条書きの要素は、同じ種類にする

こういう箇条書きはいけません：

- ユーザー一覧
- 種別変更登録
- ユーザー登録機能を追加した

１つの箇条書きに、画面名・操作・文章という異なるものが混じっています。こういった、箇条書きはstringとintとfloatが混在したリストのようなもので、病の兆候です。

以下のように、要素の種類を揃えましょう。

- ユーザー一覧画面を新規作成した
- DBに種別変更を登録した
- ユーザー登録機能を追加した

8. その他：凝った表現を使わない

思春期男子が好みそうな、格好つけた表現は使わないようにしましょう。冗長であるだけでなく、雰囲気は伝わるが、使い方が間違っている・意味不明になっていることがあります。

例えば「〜と呼ばれる〇〇」は、よく以下のような誤りを見かけます：

Rubyと呼ばれる言語で実装されています。

「Rubyと呼ばれる言語」という表現は、私は以下どちらのケースにしか使えないと思います：

「『言語』には実際には "XX" という正式名称があるが、みんな俗称の "Ruby" で呼んでいる」
「『言語』正式名称が無いので、みんな "Ruby" という通称で呼んでいる」

正式名称が"Ruby"なのに、「Rubyと呼ばれる言語」と表現するのは誤りです。「MatzLispと呼ばれる言語」ならまだ分かりますが。凝って失敗するより簡潔に「Ruby言語」と書きましょう。

補足

指摘内容の細かさについて

コメント欄やはてブで「プロダクトの品質が上がるわけではない」「厳しすぎる」といった指摘をされました。

この記事で指摘した問題点は、１か所直したからといって品質が上がるとは、私も思いません。とはいえ、簡単に改善できる問題点ばかりなので、書くときに頭に入れておいて欲しいとは思っています。また、新人のレビューやプロジェクト初期のレビューでは、あえて指摘することもありますが、普段は指摘したりはしません（指摘していられません）。

プログラミング言語なら、

early return に直しましょう
関数名を check_ナントカ にするのはよくありません
(Railsで） .where(条件).first ではなく .find(条件) を使いましょう

といったレベルのものです。

ただし、プログラミング言語には充実したlintツールがあるという違いがあります。プログラミング言語の書き手は、1人でコードの問題点を確認できます。指摘するのは人間ではなくツールなので腹も立ちません。時々、ツールに指摘されて「そんな観点もあったんだ！」と理解が深まることもあります。

日本語ではツールがないので、レビュワーがわざわざ時間をかけて指摘をしなければなりません。感情的な口論に発展することもあります。また、あえて指摘されなければ、そういう観点があると気づく機会も少ない。

まるでlintツールが無かった時代のような状況です。それにウンザリして、この記事を書きました。

例文の適切さについて

このツールを使うには Python 3.7 が必要です。やRubyと呼ばれる言語で実装されています。について指摘を受けました。プログラマーならPythonのインストール方法ぐらい分かるとか、そんなコメントを書くわけがないとか。

たしかに、どちらも良い例ではなかったと思います。

〜が必要ですについては、より自然な例はこうでしょう：

このツールを使うには cx_Oracle 5.3 が必要です。

※ cx_Oracle はビルドするのにOracleのプロプラエタリなバイナリが必要なので、ユーザー登録などの、煩雑な手順を踏まなくてはなりません。

`「〜が必要です」を使わない`について・その１

「〜が必要です」を使わないの背景にあるのは「書き手が少しの手間をかけることで、読み手の時間を節約できるなら、手間をかけて欲しい」ということです。

たしかにプログラマーならインストール方法を調べて自己解決できるでしょう。

ただし、READMEやコメントを書くのは1人ですが、読むのは何十人にもなります。書き手が１０分かけて「cx_Oracleのベストなインストール方法」のURLを書いておいてくれれば、後で読む人の合計何百分を節約できます。

`「〜が必要です」を使わない`について・その２

Python 3.7 のように、インストール済み率が高く、簡単にインストールできるツールなら〜が必要ですでも問題が起きません。

ただし、レビュワーとしては、初対面の相手に「〜必要です」と書かれた時：

特に何も考えず「〜必要です」と書いた
上記のようなことを（数秒かけて）判断して「〜必要です」と書いた

どちらなのか判断がつきません。それなりに経験がある人がcx_Oracle 5.3 が必要です。と書いてくることもあります。そのため「この人はちゃんと判断して『必要です』と書いたのか？」を確認する目的と、そういう観点があると教える目的で、あえて指摘をすることがあります。

こんなの小姑か生活指導の先生みたいで嫌です。ウンザリです。こんなレビューをする羽目になる確率を少しでも減らすべく、この記事を書いたのです。

私は岩手出身の30代で東京在住7年ですが、私も脱字だと思ってしまいます。 ↩

レビュー前に直して欲しい日本語の問題点８つ