エンジニアをしていると「ひょっとして、私が追求すべきはコードの美しさではなく、日本語の方なのでは？」などと思うことがあります。
経験を重ねていくと、コードではなく指示書やレビューコメントを書く機会も増えていくからです。

でも、日本語作文の勉強ってしたことないな……。

というわけで、「文章力の基本」という本を紹介したいと思います。
普段は何気なく書いている指示書やレビューコメント、もっと伝わりやすく書けるようになりませんか？

読んだ本「文章力の基本」について

この手の書籍にしては27万部も売れたベストセラーです。

77のテクニックを掲載した「文章力の基本」と、それをさらに33へ圧縮したお手軽版の「文章力の基本の基本」があります。

文章力の基本

文章力の基本の基本

電子書籍版がないことが残念ですが、もしこの記事を読んで気になったらご購入をオススメします。

この記事では「文章力の基本」の全7章合計77テクニックを1章ずつ簡単に要約します。せっかくですから、本書の例文ではなくコードコメントの例文を自作してみました。

それでは、以下から要約を開始します。

1章：短く書く

文章を短文にわけ、主語と述語は一つずつ、短文を順序立てて配置

悪い例


# このコードはインターフェースのテストを行い、正常入力と例外入力を定義していますが、
  例外で発生するエラータイプはデフォルトの一つだけなのですが、正常入力は12パターンもあります。

改善例


# このコードはインターフェースをテストします。正常入力テストが12個パターン。
  例外入力テストもありますが、発生させるエラータイプは1種類のみです。

悪い例でも同じエンジニアなら「12パターンもテストケース作ったのか、カバレッジは何%なの？」などと理解してくれるでしょう。しかし、そうでない人にはその努力が伝わらないかもしれません。

▽改善点

長文を短文に分解
1つの短文に主語と述語を1つずつ。(1つの文が1つの要点を担当する)
短文の順序を工夫する。(上の例では、テストコード→正常入力テスト→例外入力テストの順序にしてみました。)

2章：自然な正しい表現で書く

文の主部と述部を噛み合わせる

悪い例

# 本APIはクライアントからリクエストされたSQLクエリの結果をcsv形式で受け取ります。

改善例

# 本APIはクライアントからのSQLクエリを受取り、その実行結果をcsv形式で返却します。

▽改善点
　- 悪い例では「本APIは(主部)→csv形式で受け取る(述部)」と噛み合っていない。（csvで受け取るのはクライアントのはず）
　- それを「本APIは→SQLクエリを受取り→csv形式で返却」と噛み合わせた。

急いで日本語コメントを書いていたらやりがちなパターンです。
悪い例でも意味は通じますが、文を読み解く負荷はできるだけ軽減したいものです。

中途半端な表現で文を曖昧にしない

悪い例

# 本APIが実現することには、会員の無効化と有効化があります。

改善例

# 本APIの機能には会員の無効化と有効化があります。

思い切った改善例

# 本APIの機能は会員の無効化と有効化です。

▽改善点

悪い例のように「こと」はよく使われますが、意味を曖昧にするため利用は避けるべきです。
「実現すること→機能」とすることで、より意味が明確になります。
多少意味が変わったとしても思い切った改善例のように短く断定するのもアリかも。

主部と述部が明確で短文で言い切る文ほど読みやすいです。一方で、短文で言い切るのはなかなか勇気がいります。
そのコードを十分に把握していないとなかなか書けません。

上記の例文では「こと」を使うべきではないと言いましたが、同様に「もの」「そういう」なども要注意です。

3章：言いたいことを明確にする

何を伝えたいのか?　その論理構成を整理してから書く

今までは文の工夫でしたが、ここは文章（というよりも段落？）について述べています。

悪い例

# 昨今の流れから、このAPIはサーバレスにデプロイする構成にしました。コードで環境を管理が可能で、
　yamlで定義するので、納品や検収も簡単になる。

改善例

# このAPIはサーバレスで開発しました。
　yamlファイルで環境を定義できるので、検収や納品がより簡単になりました。

▽改善点

悪い例は論理がバラバラです。段落の結論がふわっとして締まりが悪いです。考えながら文章を書いているとこうなりがちです。
改善例では、「サーバレスにした(判断) → yamlファイルで~(根拠) → 検収や納品が簡単(理由)」としてみました。

私はこのタイプの間違った文章をよく書いてしまいます。おそらく、構成を考えずにとりあえずコードを書き始め、後からコメントで補足するせいだと思います。

大切なのは「要点を短文に分解し、短文を論理的順序に配置する」ということです。
これは文章の極意ですが、作文能力だけではなく論理的思考も求められます。クリティカルシンキングの本を読み、MECE・ロジックツリーなどの論理思考法も把握しておくべきかもしれません。

4章:分かりやすく書く

かかり→受ける関係の語句はなるべく近くに配置する

悪い例


# [TODO] なるべく、以下はtry~except文による分岐ではなく、
　入力パターンごとにif文で分岐させて対処するべき。

改善例１


# [TODO] 以下はtry~except文による分岐ではなく、
　なるべく入力パターンごとにif文で対処するべき。

改善例２


# [TODO] 以下のtry~except文はなるべくif文に変更すべき。
　入力パターンごとに処理を分けることで、エラーに対処しやすくなる。

▽改善点

悪い例では「なるべく → if文で対処する」のかかり受けが離れて配置されています。
これを近くに配置しなおすことで、「なるべく→if文で対処する」という要点が伝わりやすくなります。
改善例２では「主文を最初に置く」工夫を追加しています。これによって、主文→補足文のつながりが分かりやすくなります。

他にも、以下のような例もあります。

悪い例


> 「すべて私の言うことは間違っていた」（すべて→間違っていた）

> 「私は、彼はテストコードを重視しているけど、
　　その工数が足かせになってユーザーの要望に対応できていないのは問題と思う」（私は→思う）

改善例


> 「私の言うことはすべて間違っていた」

> 「テストコードを重視するあまりユーザーの要望に対応できなくなっている。
　　私はこの現状を問題だと思う」

蛇足ですが、テストコードの工数と機能のリリース速度の問題は根が深いですね。本質的にはリリース速度を向上するために、テストコードを書いているはずなのですが……。

曖昧な接続語句を使わない

悪い例


# このconfigにトークンを設定することで、データベースへの接続を管理している。

改善例


# このconfigでトークンを管理し、データベースへ接続する。

▽改善点

「することで、」「の中で、」「といった、」などの曖昧な接続語句は使うべきではありません。
「configで管理」→「データベースに接続する」という2つの要点とその順序を明確にすべきです。

上記の悪い例はそんなに悪いとは言い切れませんが、開発物のドキュメントとしてはより「短く明確に」であるべきです。

5章:簡潔に書く

読み手が知りたいことだけを書く

悪い例


# このアプリにかかわるステークホルダーは非常に多く、想定されるユーザーも多い。
　市民体育館を利用したい人に、その利用料や時間帯などの情報をすばやく知らせる。
　地方行政や体育館の運営を委託された民間業者との調整の結果、
　プッシュ通知機能などの機能も追加された。そんな「市民体育館情報アプリ」である。

改善例1


# これは「市民体育館情報アプリ」である。
　市民ユーザーは利用時間や料金を検索でき、プッシュ通知も受け取ることができる。

改善例2


# 本アプリは「市民体育館情報アプリ」である。

▽改善点

悪い例は前置きから始まるが、多くの読み手は「結論」がどこにあるのかが分からずに混乱してしまいます。
改善例1は「結論」を始めにのべ、「簡潔にまとめた前置き」を後に配置。
改善例2は「結論」だけで終わらせました。

「読み手が知りたいこと」と「自分が言いたいこと」をごちゃ混ぜにしていると悪い例のような文章になってしまいますね。

無駄な語句は削る

悪い例


> そのようにして考えてみると、

> このような危険性に対して、我々がすべきことは２つほどある。

改善例


> そう考えると、

> この危険に対し、我々がすべきことは２つだ。

意味が変わらないのであれば、思い切って短くしましょう。

接続語はなるべく使わない

悪い例


アプリケーションのpush通知を有効にするためには、ユーザーの承認が必要である。
なぜなら、OS側でそのような仕様になっているからだ。
そして、AndoroidとiOSではその承認仕様が異なるので注意が必要だ。

改善例


スマホOSの仕様により、アプリからpush通知を行うにはユーザーの承認が必要である。
実装の際には、AndoroidとiOSで仕様が異なることに注意すべきだ。

本質的には「接続語を使うべきではない」ではなく「接続語が必要なくなるくらい、論理的な順序で文を配置すべき」という工夫だと思います。

特に「なぜなら」「そして」などの接続詞は順接です。
文の配置に問題がなければ、読み手は接続詞がなくても文の関係を予測できるはずです。

とはいえ、文の配置だけで論理接続を明確にするのは大変です。
個人的には「ちょっと文章をサボる」感覚で接続語句を使ってしまうのは問題ないと思います。

6章:共感を呼ぶように書く

読み手の疑問にちゃんと答える

悪い例

# このAPIにはテストコードはなく、JSONをやり取りするWEB-APIです。

読み手は「このAPIにはテストコードはなく、」でその理由や事情を知りたいと思うでしょう。その直後に「JSONをやり取りするWEB-APIです。」と続くと「そんな事よりも、なんでテストを書かないの？」と疑心暗鬼になってしまいます。

書いた文によって読み手が抱えてしまう疑問には、すぐに次の文で答えるべきです。

改善例

# このAPIにはテストコードがありません。
# ユーザーテストのために開発したプロトタイプだからです。
# JSONをやり取りするWEB-APIとして開発しました。

すぐに疑問に答えることで、読み手のストレスは解消されます。

7章:表記とレイアウトにも心を配る

この章はTips集みたいなものですから、要約ではなく一例をあげるのみにします。

漢字本来の意味から離れた言葉は仮名で書く

悪い例

> 家で母親とは良く話す。

改善例

> 家で母親とはよく話す。

PCやスマホでタイピングすると自動で漢字変換されてしまいますが、これは漢字の誤用です。
他にも以下のような漢字の誤用があるので注意しましょう。

悪い例

> 食べて見たらとても美味しかった。
> まったく人間と言うものは。
> と言いたい所だが、
> ムダになってしまった事になる。

改善例

> 食べてみたらとても美味しかった。
> まったく人間というものは。
> と言いたいところだが、
> ムダになってしまったことになる。

このような語句は、本来の漢字の意味を喪失し、便利に使われて一般化してしまったと考えられます。
なので、表意文字である漢字を用いず、意味を持たない表音文字のひらがなで表記しましょう。

「文章力の基本」を読んで、疑問に思うこと

@scivola さんから有意義なご指摘があったので、本記事でも紹介させて頂きたいと思います。

ここからは、ちょっと日本語についてこだわりのある方向けの話です。
プログラマーでいうと「美しいコードにこだわりたい」というような方向けです。

「曖昧な接続語句を使わない」の節

これは『文章力の基本』の 45 のあたりですよね。ちょっと納得がいかないところでした（私には）。
いや，確かに「することで、」「の中で、」「といった、」が無意味に，あるいは不適切に使われることはよくあると思うのですが，これらを使うと曖昧になるというわけではないんですよね。

たとえば「A することで B する」が適切に使われた場合，「することで」は A が B の手段であることをはっきりさせます。
これを「A し，B する」に書き換えてしまうと，A と B の論理関係が明示されなくなります。
A が B の手段かもしれないし，単に A→B の順に行うことを言っているのかもしれないし，順序も関係なくただ A と B をそれぞれ行うことを意味するのかもしれない。
A と B の論理関係が読み手にゆだねられてしまいます。

『文章力の基本』には

常にアンテナを張ることで情報収集をしたい。

を

常にアンテナを張って情報収集をしたい。

に書き換える改善例が載っています。
こういう書き換えができるのは，「アンテナを張る」が「広く情報収集の手段を講じる」というような意味であって，「情報収集をしたい」との関係が明らかだからです。
技術文書でいつもそうであるとは期待できません。

このご指摘には私も同感です。
例えば、下記の2文を比べた時、短いという理由だけで後者が優れているのか？　という議論です。

「Aに対してBする」vs「AにBする」

私の解釈ですが、これらのABの関係性を付加する語句が間違って使われるケースが多いことが原因だと思います。
つまり「間違って使うくらいなら最初から使うな」という著者の主張なのかも。

「接続語はなるべく使わない」も同様の理由で諸手を挙げては賛成しかねます。
論理関係を明示する言葉を避けた文は，読み手に高い読解力が必要かもしれません。
日本語話者だけどネイティブではない人が読むかもしれないし，そもそも日本語ネイティブの日本語文読解力はめちゃんこ低いことが既に明らかになっていますし・・・。

こちらもその通りですね。
適切に接続語を使うことで、読み手の理解を助けることができます。
でも、接続語に頼りきって論理的順序がめちゃくちゃにならないよう、気をつけましょう。

「漢字本来の意味から離れた言葉は仮名で書く」の節

トコロ，コトの例は，「形式名詞のトコロ，コトなどは平仮名で」という話ですよね。
一方，「ひとたび事が起これば住む所を失う」という場合のコト，トコロは事柄・場所という実質的意味を担うので形式名詞ではなく，漢字で書く，と。

この話を「漢字本来の意味」という表現で説明されるのはやや抵抗を感じます。
漢字が先にあってそこから意味が離れたのではなく，場所を意味するトコロという名詞が，その意味を失った，あるいはその意味の薄れた使い方をされるようにもなり，その違いを書き分けているだけなので。
で，トコロ，コト，トキなどが形式名詞のときに平仮名を使い，そうでないとき漢字を使う，という書き分けは，いま広く普及していますが，これ以外の表記が誤用であるとは言えないだろうと思います。

上記も面白い話でしたので、転載させていただきました。
とはいえ、「ひらがなで書くべき」という本の主張を否定しないので紹介のみとさせていただきます。

最後に

いかがでしょうか。

私たちは日本語をあまり意識せずに使ってしまいますが、改めて考えると奥が深いものです。

ちゃんと伝わる日本語文章を書けるようになれば、「誰も分かってくれない」というエンジニアのストレスも少し軽減できるかもしれません。

残念ながら、私は日本語の作文力を鍛えてみましたが、上司にエンジニアリングを伝えることが出来ませんでした。

とはいえ、新しい流行のプログラミング言語を覚えるのと同じくらい、日本語を勉強しなおすことも有意義だと思います。

それでは、また別の機会で会いましょう。