「わかりにくい」という表現はわかりにくい

プログラムのコードにも自然言語のドキュメントにも当てはめられると思うのでソフトウェア開発には限らないとは思っている

主張

「わかりにくい」と書きたくなったときは、より具体的に言い換えた方が良い

相手にとってより行動可能なフィードバックになるから

例えばこの記事のタイトルは「わかりにくい」を使っているので、少しネガティブ感を覚えた人もいるはず

わかりにくさの具体化を試みる過程で、わかりにくいと感じた自分の意見を書くまえに検証できるから

よく考えたらわかりにくくはなかった、という可能性もある

言い換えのパターンと具体例

誤った理解を引き起こすという意味でわかりにくいパターン

「この関数名の意図は「〜〜」ということだと思いますが、「〜〜」という異なる意味にとられる恐れがあります。」

「〜〜という誤解を生じる」というように一般化できる

認知負荷が大きいという意味でわかりにくいパターン

「この変数xの使用箇所は実際はここからここまでですが、それに比べてスコープが広いので、xが変更される可能性を考えながら読む必要がある状態になっています。」

「〜〜という可能性を考慮しながら読む必要がある」というように一般化できる

unknown unknownがあるという意味でわかりにくいパターン

「このファイルaはこのファイルbに依存していますが、依存していることに気づくのが難しいです」

「〜〜に気づくのが難しい」というように一般化できる