online comment (オンラインコメント)

coding style

uupaa.js のコメントは、多くの場合オンラインコメントとして記述しています。

例えば、uu.ajax の GC部分では

    function gc(abort) {
        if (abort) {
            // [IE6][IE7][FIX] xhr.abort throw exception
            // http://twitter.com/uupaa/status/26953945895
            try {
                xhr && xhr.abort && xhr.abort();
            } catch (err) {}
        }
        watchdogTimer && (clearTimeout(watchdogTimer), watchdogTimer = 0);
        xhr = null;
//{@mb
        _gecko && uueventdetach(win, "beforeunload", ng); // [Gecko]
//}@mb
    }

のように、URL( http://twitter.com/uupaa/status/26953945895 )を埋め込んでいます。

http://twitter.com/uupaa/status/26953945895 の中身は次のようになっており、コードの意味と背景が分かるような記述になっています。

IE6, IE7 では xhr.about に触れることが許されないケースがあるので( xhr.about にタッチするだけで例外発生 ) try 〜 catch で囲っとくべきだったか

via http://twitter.com/#!/uupaa/status/26953945895

なぜオンラインコメントなのか

ライブラリやフレームワークのコードはどういった環境や文字コードで利用されるか分からないため、ASCIIコード以外の文字コードは原則的に利用できません。
ASCIIコード以外の文字を使うと、読めないだけではなく、実行時エラーを発生させるおそれがあるからです。

オンラインコメントのメリット

オンラインコメントは、次のような使い方ができます。

  • 日本語のコメントや、より詳細なコメントを望んでいるユーザのために利用できる
  • 資料,画像,映像を活用した説明が可能になる
  • 設計思想など、長くなりそうな場合は、短い英文とURLだけを埋め込み、ブログやツイッターに読み物の形で説明する