プログラマが心がける文章の書き方　日本語（１８）

プログラマが心がけるとよい文章の書き方には、教科書がある。

 文章の書き方
山本和彦 (株)インターネットイニシアティブ
PDF版
https://www.mew.org/~kazu/material/2008-bunshou.あpdf
HTML版
https://www.mew.org/~kazu/doc/japanese.html

上記を解説するとともに、補足と追記順次をする。
この文書もばらつきがあり、順次訂正する予定。

文責　元　~~名古屋市~~　小川清
 
 <この項は書きかけです。順次追記します。>
# 受動態を使うな、能動態を使え

これは、英文のISOをJISにする際の手引きにも記述がある。

理由は簡単。

れる、られる
https://www.kokugobunpou.com/助動詞/れる-られる/
には、受身、可能、自発、尊敬の４種類がある。敢えてわかりにくくしたいのでなければ、使わない方がよい。技術文書では尊敬は使わない。


# カタカナを使わない
技術文書であれば、外来語で、日本語訳が定着していない語は、日本語英語を併記してもよいかもしれない。プログラミング言語、商品名などであれば、英語のままでもよいかもしれない。カタカナ語にする不利益は山のようにある。

１　元の英語がわからなくなる
ライトと書いてあれば、lightかrightかわからない。
文脈依存で理解できる場合もある。
正、右ではどうしてダメなのでしょう。

２　文字列が長くなる
文章の書き方で大事なことの一つに、大切なこと以外に文字列を費やさないことです。主題以外の用語に長い文字列を使うのは、読む時間を無駄にしたり、紙面を無駄にすることになります。上記のライトは正、右にすれば２文字も節約できます。

３　単語の区切りがわからなくなる
カタカナ語を２つ以上つなげると、単語の区切りがわからなくなることがあります。ライフサイクルプロセスはlife cycle processとかいてあれば、一眼でわかるのに、カタカナ語で区切りがわからないと無駄な時間を使います。
単語の区切りに中黒・を使えば、区切りはわかりますが、文字列がより長くなります。

「外来語」言い換え提案
http://www2.ninjal.ac.jp/gairaigo/

なぜ計画者(programmer)はカタカナ語を使わない方がよいのか 
https://qiita.com/kaizen_nagoya/items/d09e5ee549c4d9a17912

# 接続詞「が」
文章を逆説的につなぐ接続詞である。
前半に同意できても後半に同意できない。
後半に同意できても前半に同意できない。
両方とも同意できるが逆の接続ではない。
せっかく同意してもらえる可能性のある文章を台無しにする。

逆説であることを証明したのでなければ、使わないのが良い。

HTML版から引用する。

「一番大切なことは「正確さ」ですが、文章を書くための最低条件は何かと聞かれれば、私は自信をもって「伝えたいことだ」と答えます。」

書き直してみる。

「一番大切なことは「正確さ」です。文章を書くための最低条件は何かと聞かれれば、私は自信をもって「伝えたいことだ」と答えます。」

正確さを一番大切だと思うことと、伝えたいことが最低条件であることは、矛盾するかどうかはわからない。「が」を使うことで、より少数の人にしか伝わらなくならないか検討するとよい。

参考文献 マークピーターセン著:「日本人の英語」、岩波新書

# 「ので」「ため」を使わない。
山本和彦さんは上記資料にかかれていない。「が」の使用と同等にやらない方がよいと感じていることに「ので」「ため」がある。

理由は「が」と似ている。前後の関係の論理性を証明してない時に、「ので」「ため」を使うと同意できる読者を減らす可能性がある。

HTML版で
「実はもっと上にも階段がありますが、ここまででも十分恥ずかしいので、これ以上恥ずかしいことをしらふのときに言いたくありません。」

書き直してみる。

「実はもっと上にも階段があります。ここまででも十分恥ずかしい。これ以上恥ずかしいことをしらふのときに言いたくありません。」

人によっては、「ので」ではなく、「そして」とか補って読むかもしれない。
必ずしも「ので」である必要はない。

伝えたいことは、より少数の人に伝わればよいというのが著者の意図であれば、どのように書いてもよい。より多くの人に伝えたいと思えば、読者を限定するような書き方を改めるとよいかもしれない。

# 参考文献(reference)
マークピーターセン著:「日本人の英語」、岩波新書
https://www.amazon.co.jp/dp/B00QT9XB1G/ref=dp-kindle-redirect?_encoding=UTF8&btkr=1

「正確な文章の書き方」
https://researchmap.jp/jonu5pceg-50024/

ソフトウェア品質シンポジウムでBest Paper Effective Awardを受賞するコツ？
https://qiita.com/kazuo_reve/items/b5e740328bebad179414

## 自己参照(self reference)
なぜ計画者(programmer)はカタカナ語を使わない方がよいのか　日本語（２２）
https://qiita.com/kaizen_nagoya/items/d09e5ee549c4d9a17912

カタカナ語で選手権 日本語(17)
https://qiita.com/kaizen_nagoya/items/f1c0384a13dd13c5e7f1

プログラマが心がける文章の書き方 日本語（１８）
https://qiita.com/kaizen_nagoya/items/af1e6207ccaa063dafb8

プログラマとして、「プログラムを書く時、文章を書く時、言い訳をする時」に心がけていること。仮説(87)
https://qiita.com/kaizen_nagoya/items/7e5700db01727cb516fc

プログラマの「日報、週報、月報、年報」考
https://qiita.com/kaizen_nagoya/items/97ad8ac9217c12c3bb69

記事を書くときに注意していること
https://qiita.com/kaizen_nagoya/items/3a6e08309231aa05fb27

docker不調
https://qiita.com/kaizen_nagoya/items/167c0efd482dbf2cec1f

文章の書き直し例
https://researchmap.jp/jowsulkh9-45644/#_45644

「ソフトウェアドキュメンテーション」１１個の良いことと５つの経験則
https://qiita.com/kaizen_nagoya/items/7d8c6d50023e78f969b3

「ソフトウェア品質シンポジウムでBest Paper Effective Awardを受賞するコツ？」に付け加えたい5つのこと
https://qiita.com/kaizen_nagoya/items/70a53f19d95d571a0e48

物理記事　上位100
https://qiita.com/kaizen_nagoya/items/66e90fe31fbe3facc6ff

数学関連記事１００
https://qiita.com/kaizen_nagoya/items/d8dadb49a6397e854c6d

言語・文学記事　１００
https://qiita.com/kaizen_nagoya/items/42d58d5ef7fb53c407d6

医工連携関連記事一覧
https://qiita.com/kaizen_nagoya/items/6ab51c12ba51bc260a82

通信記事１００
https://qiita.com/kaizen_nagoya/items/1d67de5e1cd207b05ef7

自動車　記事　１００
https://qiita.com/kaizen_nagoya/items/f7f0b9ab36569ad409c5

OSEK 記事で views 100,000を目指して　OSEK(8)
https://qiita.com/kaizen_nagoya/items/ff45ee55566eeff5f62e

無線網（Wi-Fi）空中線(antenna)(0) 記事一覧(209/300目標) https://qiita.com/kaizen_nagoya/items/5e5464ac2b24bd4cd001

なぜdockerで機械学習するか 書籍・ソース一覧作成中 (目標100)
https://qiita.com/kaizen_nagoya/items/ddd12477544bf5ba85e2

仮説（0）一覧（目標100現在40）
https://qiita.com/kaizen_nagoya/items/f000506fe1837b3590df

安全（0）安全工学シンポジウムに向けて: 21
https://qiita.com/kaizen_nagoya/items/c5d78f3def8195cb2409

日本語（０）一欄
https://qiita.com/kaizen_nagoya/items/7498dcfa3a9ba7fd1e68

英語(0) 一覧
https://qiita.com/kaizen_nagoya/items/680e3f5cbf9430486c7d

転職(0)一覧
https://qiita.com/kaizen_nagoya/items/f77520d378d33451d6fe

一覧の一覧( The directory of directories of mine.) Qiita(100)
https://qiita.com/kaizen_nagoya/items/7eb0e006543886138f39

プログラマが知っていると良い「公序良俗」
https://qiita.com/kaizen_nagoya/items/9fe7c0dfac2fbd77a945

LaTeX(0) 一覧　
https://qiita.com/kaizen_nagoya/items/e3f7dafacab58c499792

自動制御、制御工学一覧（０）
https://qiita.com/kaizen_nagoya/items/7767a4e19a6ae1479e6b

Rust(0) 一覧　
https://qiita.com/kaizen_nagoya/items/5e8bb080ba6ca0281927

小川清最終講義、小川清最終講義（再）計画, Ethernet(100) 英語(100) 安全(100)
https://qiita.com/kaizen_nagoya/items/e2df642e3951e35e6a53

＜この記事は個人の過去の経験に基づく個人の感想です。現在所属する組織、業務とは関係がありません。＞
This article is an individual impression based on the individual's experience. It has nothing to do with the organization or business to which I currently belong.
#### 文書履歴(document history)
ver. 0.01 初稿 20181218 朝
ver. 0.02 参考文献追記 20181218 昼
ver. 0.03 「ため」追記 20181218 夕
ver. 0.04 補足　20191017
ver. 0.05 参考文献追記 ソフトウェア品質シンポジウムでBest Paper Effective Awardを受賞するコツ？　20210117
ver. 0.06 補足、タグ追加 20210806
ver. 0.07 ありがとう追記　20230508
## 最後までおよみいただきありがとうございました。
いいね　💚、フォローをお願いします。
####  Thank you very much for reading to the last sentence.
Please press the like icon 💚　and follow me for your happy life.