……というのが今年の個人的なキーフレーズだったのかもしれない、とふと思った。そういうキーフレーズに対してどういう取り組みをしてきたのか、ここで振り返ってみる。やってみたらあまりオチがない感じだった。
自然に読み下せるように書く
「setNewValue 関数に val 変数を渡す」と「setNewValue(val) する」だと前者のほうが好ましいと思う。文脈から読み方を想像してもらうよりは、明示的に書いてあって自然に読み下せるようになっているほうがありがたい。あるいは、インラインコードに思いを込めすぎないようにする、とも言い表せるのかもしれない。
文章のつながりを意識する
文の羅列があって、それではこれを読んでください、という態度だとなかなか伝わらないと思う。使っているツールにもよるけど、見出しや箇条書きをうまく使うようにするとか、接続詞をちゃんと使うとか、そのあたりを気をつけるとよさそう。
あとは、前提・結論・感想・意見などがごちゃごちゃになっているよりは、はっきり分かれているほうがいい。このあたりは「理科系の作文技術」を読んでもらうのがよさそう。連日同じ本の話をしている気がする。
言語化を厭わない
例えば、ちょっといまいちな実装があったとして、「この実装はいまいちですね」というレビューコメントを付けても、レビュワーにとってはどうしたらいいのか分からないと思う。何がどういまいちなのかを噛み砕いて言葉にした上でコメントを付けるようにする。「一貫性がなくなっている」「責務が大きすぎる」など、「いまいち」という言葉で済ませないように心がけている。
(細かい) 綴りには気をつける
細かいけど、英単語やコードネームなどの綴りが間違っていると、一見してそっちに気を取られてしまう。すくなくとも自分が書くときはできるだけ綴りを間違えないように書いていきたい。
