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

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

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

こんな指摘を、新人が入ってくるたびにコードレビューやドキュメントレビューで繰り返しています。

しかも、新人はなぜみんな**同じような分かりにくい表現**をつかってきます。
なんなんでしょう？工学部では、こんな言葉遣いをするよう指導してるんでしょうか？

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

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

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

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

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

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

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

例えば、

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

ここの「のが」は若者言葉です。

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

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

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

```
NG 知見が得られた
OK 〜であることが分かった
OK うるせえ、もうこの話は終わりだ

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

また、[不思議の国のSE用語](https://qiita.com/t_nakayama0714/items/478a8ed3a9ae143ad854)はSE以外の人が読む可能性を考慮して使ってください。

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

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

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

読み手の負荷を軽くするために、**語尾（助動詞）** を書きましょう。

特に

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

この３つについては[RFC2119](https://www.ipa.go.jp/security/rfc/RFC2119JA.html)で規定されているくらいですから、はっきり書きましょう。

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

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

あなたはPython 3.7のインストールを知っているかもしれません。brewとpyenvとasdfのメリット・デメリットも知っているでしょう。

しかし、読み手はそうとは限りません。

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

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

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

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

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

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

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

「助動詞を使う（体言止めをしない）」の一種ですが、「〜対応」は避けてください。

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

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

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

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

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

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

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

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

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

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

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

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

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

格好つけた表現は使わないようにしましょう。冗長であるだけでなく、**単に使い方が間違っている**場合があります。

例えば、以下のような表現は誤りです：

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

「Rubyと呼ばれる言語」という表現は「『言語』には "XX" という正式名称があるが、みんな俗称の "Ruby" で呼んでいる」ときに使うものです。正式名称が"Ruby"なのに、「Rubyと呼ばれる言語」と表現するのは誤りです。「MatzLispと呼ばれる言語」ならまだ分かりますが。簡潔に「Ruby言語」と書きましょう。

# 補足

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

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

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

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

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

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

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

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

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

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

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

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

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

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

あなたのチームメンバー全員がmacOS上でpyenvを使っているなら、単に「Python 3.7が必要です」でも問題は起きません。

そうではないなら、

- 「ここで書き手が15分かけてでも、Python 3.7のインストール方法を案内すべき。その方がチーム全体の時間を節約できる」
- 「うちのチームメンバーはそれなりにベテランなので自力でPython 3.7をインストールできる。今、自分がインストール方法を案内するのは、むしろ時間の無駄」

という判断をしなければなりません。

そして、レビュワーとしては、とくにレビュイーが初対面の時は、

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

どちらなのか判断がつかないので「〜必要です」がどういう意味なのか質問せざるをえないことｇあります。

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