プログラマが心がけるとよい文章の書き方には、教科書がある。
文章の書き方
山本和彦 (株)インターネットイニシアティブ
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)はカタカナ語を使わない方がよいのか
接続詞「が」
文章を逆説的につなぐ接続詞である。
前半に同意できても後半に同意できない。
後半に同意できても前半に同意できない。
両方とも同意できるが逆の接続ではない。
せっかく同意してもらえる可能性のある文章を台無しにする。
逆説であることを証明したのでなければ、使わないのが良い。
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)
プログラマとして、「プログラムを書く時、文章を書く時、言い訳をする時」に心がけていること。仮説(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
＜この記事は個人の過去の経験に基づく個人の感想です。現在所属する組織、業務とは関係がありません。＞
文書履歴(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.