「ドキュメントに気合いれている」、「綺麗なドキュメント」と良く言われるが実は一つのことを年頭においているだけ。

それは可読性。いわゆる読みやすさ。

昨日、後輩の書いたドキュメントをチェックしたがめちゃくちゃ読みづらいので「見にくい」といったら、「みやすいですよ」と突っかかってくる。
かなりムカついて、感情的に応対した俺は駄目駄目だけど、しかし間違っちゃいない。

import java.util.*; public class Foo implements Runnable {    public static void main(String args) throws Exception {       System.out.println("test");    }    public void run() {       // call to other method       Other o = new Other();       o.execute();    } }

と

import java.util.*; public class Foo implements Runnable {    public static void main(String args) throws Exception {       System.out.println("test");    }    public void run() {       // call to other method       Other o = new Other();       o.execute();    } }

とどちらが見やすいという話だったのに、「前者は見やすいですよ」と一点張り。なんで？

• コーディングを書く場合は等倍フォントの方が可読性が高い。
• ボルドは幅が増えるので可読性・一行の情報量が低くなる。
• イタリックは確実に見にくい
• 色の明るさが近い

可読性はただ見やすい、というだけでは駄目で、コーディング等読んで理解しないといけない。
後で調べる用。

• 色の波長
• 色の明るさ

しかし、感情的になってしまったなぁ。大反省。ちゃんと「見づらい」じゃなくて「読みづらい」と言えば良かった。