私はウンザリしています。
「○○対応」は曖昧なのでやめてください。「○○が■■になるバグを修正した」の方が直接的です。
こんな指摘を、新人が入ってくるたびにコードレビューやドキュメントレビューで繰り返しています。
しかも、新人はなぜみんな同じような分かりにくい表現をつかってきます。
なんなんでしょう？工学部では、こんな言葉遣いをするよう指導してるんでしょうか？
「レビューを依頼する前にこれを読んどいて！」と言える記事なり本なりがあれば良かったのですが、良いものが見つけられなかった（ご存知なら教えてください）ので、とりあえずレビューでよく指摘する日本語の文章の問題点や変な表現ポイントを列挙しました。
なお「コメントは必要十分な量を書く」「チケット番号やWikiのURLを書く」といった、良く知られた・日本語に限定されない話題は省略しています。
1. 俗称を使わない・造語しない
製品名・機能名などは正式なものを使いましょう。大抵はUIなりマニュアルなどで使われている名前が正式です。
正式な名前がわからなくなっている事もあります。開発者と利用者で呼び方が違うなど（レガシーシステムでありがち）。その場合も勝手にどちらかを選ぶのではなく、チーム内でルールを決めてください。
2. 方言・業界用語を使わない
さすがに「ファイルを開ぐのがいずいっちゃ」等のモロな方言を見たことはありませんが、首都圏方言や若者言葉は時々見かけます。
例えば、
「listよりsetのが高速です」
ここの「のが」は若者言葉です。
また、工学科・情報科の中でしか通じない言葉も見逃されがちです。例えば：
知見が得られた
エビデンスが無い
これらは、一般的な言い方に直しましょう。
NG 知見が得られた
OK 〜であることが分かった
OK うるせえ、もうこの話は終わりだ
NG エビデンスが無い
OK Excelファイルにスクリーンショットの画像が添付されていない
OK 疫学的に十分な検証がなされていない
また、不思議の国のSE用語はSE以外の人が読む可能性を考慮して使ってください。
3. 助動詞を使う（体言止めをしない）
助動詞を省略すると、時制・完了・必然性などが曖昧になります。例えば「メールを配信」は文脈により、以下の意味になることがあります:
- 「メールを配信しなければならない」
- 「メールを配信した方がよい」
- 「メールを配信してもよい」
- 「これからメールを配信する予定だ」
- 「メールを配信した」
読み手の負荷を軽くするために、語尾（助動詞） を書きましょう。
特に
- 「〜してもよい」（may）
- 「〜するべきである」(should)
- 「〜しなければならない」(must)
この３つについてはRFC2119で規定されているくらいですから、はっきり書きましょう。
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. 「○○対応」を使わない
「助動詞を使う（体言止めをしない）」の一種ですが、「〜対応」は避けてください。
例えばこんなコメントです：
# チケット#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をインストールできる。今、自分がインストール方法を案内するのは、むしろ時間の無駄」
という判断をしなければなりません。
そして、レビュワーとしては、とくにレビュイーが初対面の時は、
- 上記のようなことを（数秒かけて）判断し、あえて「〜必要です」とだけ書いた
- 特に何も考えず「〜必要です」と書いた
どちらなのか判断がつかないので「〜必要です」がどういう意味なのか質問せざるをえないことｇあります。
こんなの小姑か生活指導の先生みたいで嫌です。ウンザリです。こんなレビューをする羽目になる確率を少しでも減らすべく、この記事を書いたのです。