1. tonluqclml

    No comment

    tonluqclml
Changes in body
Source | HTML | Preview

この記事では、私がコードレビューでよく指摘する日本語の文章の問題点変な表現ポイントを列挙しました。

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

何故この記事を書いたのか?

私はウンザリしているのです。

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

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

「レビューを依頼する前にこれを読んどいて!」と言える記事なり本なりがあれば良かったのですが、良いものが見つけられなかった(ご存知なら教えてください)ので、とりあえず書いたのがこの記事です。

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

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

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

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

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

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

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

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

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

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

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

3. 助動詞を使う(体言止めをしない)

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

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

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

特に

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

この3つについては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. 箇条書きの要素は、同じ種類にする

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

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

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

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

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