1. tonluqclml

    No comment

    tonluqclml
Changes in body
Source | HTML | Preview
@@ -1,156 +1,156 @@
私はウンザリしています。
> 「○○対応」は曖昧なのでやめてください。「○○を修正した」の方が直接的です。
こんな指摘を**新人が入ってくるたびにコードレビューで繰り返しています**。どうも、プログラマー(と言うか理系?)には独特の言語文化があり、**みんな同じような分かりにくい表現をしてしまう**ようです。
「レビューを依頼する前にこれを読んどいて!」と言える記事なり本なりがあれば良かったのですが、良いものが見つけられなかった(ご存知なら教えてください)ので、とりあえずコードレビューでよく指摘する**日本語の文章の問題点**や**変な表現**ポイントを列挙しました。
なお「コメントは必要十分な量を書く」「チケット番号やWikiのURLを書く」といった、良く知られた・日本語に限定されない話題は省略しています。
# 1. 俗称を使わない・造語しない
製品名・機能名などは正式なものを使いましょう。大抵はUIなりマニュアルなどで使われている名前が正式です。
正式な名前がわからなくなっている事もあります。開発者と利用者で呼び方が違うなど(レガシーシステムでありがち)。その場合も勝手にどちらかを選ぶのではなく、チーム内でルールを決めてください。
# 2. 方言・業界用語を使わない
どの出身地・世代でも伝わる言葉を選びましょう。
さすがに「ファイルを開ぐのがいずいっちゃ」等のモロな方言を見たことはありませんが、首都圏方言や若者言葉は時々見かけます。
例えば、
```
「listよりsetのが高速です」
```
-は、地方のちょっと年配の人は脱字(「〜の方が〜」の「方」が抜けている)と思うでしょう。
+は、地方の年配の人は脱字(「〜の方が〜」の「方」が抜けている)と思うでしょう。
また、**工学科・情報科の中でしか通じない言葉**も見逃されがちです。例えば:
```
知見が得られた
エビデンスが無い
```
これらは、一般的な言い方に直しましょう。
```
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言語」と書きましょう。