1. tonluqclml

    No comment

    tonluqclml
Changes in body
Source | HTML | Preview
@@ -1,217 +1,217 @@
私はウンザリしています。
> 「○○対応」は曖昧なのでやめてください。「○○を修正した」の方が直接的です。
こんな指摘を**新人が入ってくるたびにコードレビューで繰り返しています**。どうも、プログラマー(と言うか理系?)には独特の言語文化があり、**みんな同じような分かりにくい表現をしてしまう**ようです。
「レビューを依頼する前にこれを読んどいて!」と言える記事なり本なりがあれば良かったのですが、良いものが見つけられなかった(ご存知なら教えてください)ので、とりあえずコードレビューでよく指摘する**日本語の文章の問題点**や**変な表現**ポイントを列挙しました。
なお「コメントは必要十分な量を書く」「チケット番号やWikiのURLを書く」といった、良く知られた・日本語に限定されない話題は省略しています。
(※コメント欄などの指摘を受け「補足」)
# 1. 俗称を使わない・造語しない
製品名・機能名などは正式なものを使いましょう。大抵はUIなりマニュアルなどで使われている名前が正式です。
正式な名前がわからなくなっている事もあります。開発者と利用者で呼び方が違うなど(レガシーシステムでありがち)。その場合も勝手にどちらかを選ぶのではなく、チーム内でルールを決めてください。
# 2. 方言・業界用語を使わない
どの出身地・世代でも伝わる言葉を選びましょう。
さすがに「ファイルを開ぐのがいずいっちゃ」等のモロな方言を見たことはありませんが、首都圏方言や若者言葉は時々見かけます。
例えば、
```
「listよりsetのが高速です」
```
は、地方の年配の人は脱字(「〜の方が〜」の「方」が抜けている)と思うでしょう[^3]。
[^3]: 私は岩手出身の30代で東京在住7年ですが、私も脱字だと思ってしまいます。
また、**工学科・情報科の中でしか通じない言葉**も見逃されがちです。例えば:
```
知見が得られた
エビデンスが無い
```
これらは、一般的な言い方に直しましょう。
```
NG 知見が得られた
OK 〜であることが分かった
NG エビデンスが無い
OK 科学的に証明はされていない
OK Excelファイルにスクリーンショットの画像が添付されていない
```
また、SE用語([不思議の国のSE用語](https://qiita.com/t_nakayama0714/items/478a8ed3a9ae143ad854))はSE以外の人が読む可能性がないか注意して使ってください。
# 3. 助動詞を使う(体言止めをしない)
助動詞を省略すると、時制・完了・必然性などが曖昧になります。例えば「メールを配信」は文脈により、以下の意味になることがあります:
- 「メールを配信しなければならない」
- 「メールを配信した方がよい」
- 「メールを配信してもよい」
- 「これからメールを配信する予定だ」
- 「メールを配信した」
もちろん文脈から推測できることが大半ですが、読み手の負荷を軽くするために、**語尾(助動詞)**をはっきり書きましょう。
特に
- 「〜してもよい」(may)
- 「〜するべきである」(should)
- 「〜しなければならない」(must)
この3つについては[RFC2119](https://www.ipa.go.jp/security/rfc/RFC2119JA.html)で規定されているくらいですから、はっきり書きましょう。
# 4. 「〜が必要です」を使わない
```
このツールを使うには Python 3.7 が必要です。
```
読み手にとっては「必要です」では情報が不十分で、以下のように思案することになります。
- Python 3.7 をインストールするにはどうすればいいのか?
- 必要だとして、今すぐPython 3.7 をインストールするべきなのか?このドキュメントを全て読んでからインストールするべきなのか?
- もし Python 3.7 をインストールできない場合はどうすればいいのか?
何かが必要なら、明示的に指示した方が、読み手を迷わせません。また、手順書などへのリンクを置くと、なお親切でしょう。
```
このツールを使う前に Python 3.7 をインストールしてください。
インストール方法はこちら → http://example.com
```
# 5. 「つまり」「要するに」「端的に言うと」「簡単に言うと」「結論から言うと」などは削除する
**単に削除しましょう。**
**これらの定型句は情報を増しません。**口語での「ええっと」「その〜」などと同じ、心のうめきに過ぎないからです。
これらを使いたい・思わず使ってしまう人は、自分の文章を見直してください。「端的に言うと」「簡単に言うと」「結論から言うと」と書いている文章は、後続する文が**端的にも、簡単にも、結論から言っているわけでもない**ことが、実際には(なぜか)多いからです。
# 6. 「○○対応」を使わない
例えばこんなコメントです:
```ruby
# チケット#143567の不具合対応
# SPA化対応
```
「〜対応」をつけると、なんだかそれっぽい雰囲気になります。でも、「〜対応」を付けたからといって、情報量が増えるわけでも、わかりやすくなるわけでもありません。
「〜対応」は単に削除しましょう。あるいは、単語で済ませず本来書くべき説明を書きましょう。
```ruby
「対応」を単に削除
# チケット#143567の不具合
# SPA化
丁寧に書く
# 未ログイン時に表示が崩れる不具合を回避するためのハック(チケット#143567)
# SPA化のために、外部向けAPIと同様の物を別立てで実装している
```
# 7. 箇条書きの要素は、同じ種類にする
こういう箇条書きはいけません:
```
- ユーザー一覧
- 種別変更登録
- ユーザー登録機能を追加した
```
1つの箇条書きに、画面名・操作・文章という異なるものが混じっています。こういった、箇条書きはstringとintとfloatが混在したリストのようなもので、病の兆候です。
以下のように、要素の種類を揃えましょう。
```
- ユーザー一覧画面を新規作成した
- DBに種別変更を登録した
- ユーザー登録機能を追加した
```
# 8. その他: 凝った表現を使わない
思春期男子が好みそうな、格好つけた表現は使わないようにしましょう。冗長であるだけでなく、**雰囲気は伝わるが、使い方が間違っている・意味不明になっている**ことがあります。
例えば**「〜と呼ばれる〇〇」**は、よく以下のような誤りを見かけます:
```
Rubyと呼ばれる言語で実装されています。
```
「Rubyと呼ばれる言語」という表現は、私は以下どちらのケースにしか使えないと思います:
- 「『言語』には実際には "XX" という正式名称があるが、みんな俗称の "Ruby" で呼んでいる」
- 「『言語』正式名称が無いので、みんな "Ruby" という通称で呼んでいる」
正式名称が"Ruby"なのに、「Rubyと呼ばれる言語」と表現するのは誤りです。「MatzLispと呼ばれる言語」ならまだ分かりますが。凝って失敗するより簡潔に「Ruby言語」と書きましょう。
# 補足
## 指摘内容の細かさについて
コメント欄やはてブで「プロダクトの品質が上がるわけではない」「厳しすぎる」といった指摘をされました。
-この記事で指摘した問題点は、1か所直したからといって品質が上がるとは、私も思いません。とはいえ、簡単に改良できる問題ばかりなので、書くときに頭に入れておいて欲しいとは思っています。
+この記事で指摘した問題点は、1か所直したからといって品質が上がるとは、私も思いません。とはいえ、簡単に改良できる問題ばかりなので、書くときに頭に入れておいて欲しいとは思っています。また、新人のレビューやプロジェクト初期のレビューでは、あえて指摘することもありますが、普段は指摘したりはしません(指摘してられません)。
プログラミング言語なら、
- early return に直しましょう
- 関数名を `check_ナントカ` にするのはよくありません
- (Railsで) `.where(条件).first` ではなく `.find(条件)` を使いましょう
-といったレベルのものです。すでに稼働しているなら、あえて直したりはしない問題点です。
+といったレベルのものです。
-ただし、プログラミング言語には充実したlintツールがあるという違いがあります。プログラミング言語の書き手は、1人でコードの問題点を確認できます。指摘するのは人間ではなくツールなので腹も立ちません。また、時々、ツールに指摘されて「そんな観点もあったんだ!」と理解が深まることもあります。
+ただし、プログラミング言語には充実したlintツールがあるという違いがあります。プログラミング言語の書き手は、1人でコードの問題点を確認できます。指摘するのは人間ではなくツールなので腹も立ちません。時々、ツールに指摘されて「そんな観点もあったんだ!」と理解が深まることもあります。
-日本語ではツールがないので、レビュワーがわざわざ時間をかけ、細かい指摘をしなければなりません。ときどき感情的な口論が起きることもあります。「『○○対応』でも品質に影響しないと思います!」なんて
+日本語ではツールがないので、レビュワーがわざわざ時間をかけ指摘をしなければなりません。感情的な口論に発展することもあります。また、あえて指摘されなければ、そういう観点があると気づく機会も少ない
-まるでlintツールが無かった20年前のような状況です。それにウンザリして、この記事を書きました。
+まるでlintツールが無かった時代のような状況です。それにウンザリして、この記事を書きました。
## 例文の適切さについて
`このツールを使うには Python 3.7 が必要です。`や`Rubyと呼ばれる言語で実装されています。`について指摘を受けました。プログラマーならPythonのインストール方法ぐらい分かるとか、そんなコメントを書くわけがないとか。
-かに、どちらも良い例ではなかったと思います。
+たしかに、どちらも良い例ではなかったと思います。
`〜が必要です`については、より自然な例はこうでしょう:
```
このツールを使うには cx_Oracle 5.3 が必要です。
```
※ cx_Oracle はビルドするのにOracleのプロプラエタリなバイナリが必要なので、ユーザー登録などの、煩雑な手順を踏まなくてはなりません。
## `「〜が必要です」を使わない`について・その1
`「〜が必要です」を使わない`の背景にあるのは「書き手が少しの手間をかけることで、読み手の時間を節約できるなら、手間をかけて欲しい」ということです。
たしかにプログラマーならインストール方法を調べて自己解決できるでしょう。
ただし、READMEやコメントを書くのは1人ですが、読むのは何十人にもなります。書き手が10分かけて「cx_Oracleのベストなインストール方法」のURLを書いておいてくれれば、後で読む人の合計何百分を節約できます。
## `「〜が必要です」を使わない`について・その2
Python 3.7 のように、インストール済み率が高く、簡単にインストールできるツールなら`〜が必要です`でも問題が起きません。
ただし、レビュワーとしては、初対面の相手に「〜必要です」と書かれた時:
- 特に何も考えず「〜必要です」と書いた
- 上記のようなことを(数秒かけて)判断して「〜必要です」と書いた
どちらなのか判断がつきません。それなりに経験がある人が`cx_Oracle 5.3 が必要です。`と書いてくることもあります。そのため「この人はちゃんと判断して『必要です』と書いたのか?」を確認する目的と、そういう観点があると教える目的で、あえて指摘をすることがあります。
こんなの小姑か生活指導の先生みたいで嫌です。ウンザリです。こんなレビューをする羽目になる確率を少しでも減らすべく、この記事を書いたのです。