ドキュメントやサポート、チャットでの説明で日本語を書く機会は多いと思います。 「プログラムについて日本語で伝える」ノウハウは、単に日本語の美しさだけではない部分もあるので難しい点です。
今日はその1つ、「日本語ぶった切りプログラム」というアンチパターンを見つけたので共有したいと思います。 アンチパターンとして名付けて、伝えやすく・覚えやすくしようという目論見です（今後の僕自身のためにも）。
アンチパターン:日本語ぶった切りプログラム
このアンチパターンは、日本語の文の途中にプログラムが入ってしまうアンチパターンです。 とくに「以下のように、」や「このような、」のあとにプログラムの引用を文中に書いてしまって、日本語が途中で切れてしまうものです。
以下がアンチパターンの例です
time_it 関数では以下のように、
def time_it():
…
…
関数の冒頭で処理を実行しています。
「以下のように、」の後にプログラムが貼られることで日本語が途中で切れてしまっています。 書き手の意図としては「この関数では以下のように〜『ここでプログラムを指差す』」というイメージはわかりますが、 読み手としてみるとプログラムのどこに集中して読めば良いのかが分かりにくくなります。
問題
以下のような問題が考えられます。
- プログラムを読ませられる意図が事前に分からないので、どの点に注目して読めば良いのか分かりにくい
- プログラムを読んでいる間にも、プログラム前に説明された日本語を記憶しておく必要があり疲れる
改善方法
プログラムを貼って説明したいこと・伝えたいことを、まず1文で表現してからコードを貼りましょう。
time_it 関数では以下のように、関数の冒頭で 〜 という処理を実行しています。
def time_it():
…
…
time_it 関数の冒頭で 〜 することによって、〜の意味があるためです。
* 〜するので、〜しやすい
* 〜するので、〜がわかりやすい
細かい説明や意図の説明は、プログラムを貼った後にすると良いと思います。 逆にプログラムの前に説明しすぎると、それはそれで前の文を覚えきれなくなってしまうので避けましょう。
アンチパターン名 日本語ぶった切りプログラム でした。
