イライラ表現4:肯定を表す二重否定
大手ITベンダーでSEを務めるJさんは、ドキュメントを書く際に、二重否定の表現にならないように気を付けている。
ITの現場のドキュメントでよく見られる二重否定の表現の例を、以下の図に3つ挙げた。いずれも、頭にスッと入ってこないものばかりだろう。
このうち例3の「管理対象外以外」という表現は、極端な例だと思うかもしれない。しかしJさんによれば、ドキュメントのなかで「管理対象外」という言葉を使った後に、それ以外という意味で「管理対象外以外」としてしまうことは珍しくないという。
たいていの場合、二重否定の表現は否定を使わない表現に修正できる。例1は「条件によらずすべてのケースにreturn文が存在する」という意味である。例2は「パラメーターが指定されている場合のみ、更新を許可する」、例3は「管理対象かどうかをチェックする」となる。見比べると、圧倒的に分かりやすくなったことに気付くはずだ。
ドキュメントを推敲する過程で、二重否定の表現は比較的見つけやすい。その際には、できるだけ否定を使わない表現に修正しておきたい。
イライラ表現5:長い一文
1つの文が長い。これも、ITの現場のドキュメントによく見られるイライラ表現である。象徴的な例を次に挙げる。
- ファイルを編集する際、先にファイルをチェックアウトしたユーザーがチェックインするまで、他のユーザーは同じファイルを編集できないが、チェックインする前にシステムからログアウトした場合は、ファイルを更新せずに他のユーザーがチェックアウトできるようにする。
一般的なチェックインとチェックアウトの仕組みを説明している文だが、非常に分かりにくいだろう。この長い一文は、次のように分割できる。
- ユーザーがファイルを編集する際、ファイルをチェックアウトできるのは下記(1)(2)のどちらかの場合である。
(1)他のユーザーがファイルをチェックアウトしていない場合
(2)他のユーザーがファイルをチェックアウトした後、チェックインする前に、システムからログアウトした場合
なお(2)の場合、システムはチェックアウトされる前のファイルを保持する。
このように、長い一文は分割することで、飛躍的に分かりやすくなる。文を分割するときには、要素の一部を箇条書きや図表として分離すると、さらに効果的である。
また、長い一文と同じように、読点(、)を入れない文も分かりにくい。適宜、読点を入れて分かりやすさを高めたい。