プログラマが心がけるとよい文章の書き方には、教科書がある。
文章の書き方
山本和彦 (株)インターネットイニシアティブ
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.