Hatena::ブログ(Diary)

latest log このページをアンテナに追加 RSSフィード

2011-08-30

mofmof.js で日本語コメントの併記を始めました

uupaa.js の開発中に、

  1. 図形を交えたり、コードの由来を説明する外部リンクをソースコードに埋め込む オンラインコメントスタイル おすすめ
  2. 独自○○ より オレオレ○○ と呼べばいいよ。オレオレライブラリとか、オレオレスタイルとか
  3. オレオレコーディングスタイルを発明せず、JS特有の事情を考慮しつつ、既存のコーディングスタイルを流用するといいよ
  4. == ではなく === おすすめ
  5. typeof hoge == "undefind" より hoge === void 0 おすすめ
  6. ナビ子記法 おすすめ

など、2008年頃は存在しても注目されてなかったり、存在もしなかった用語や用法をこさえたりと、色々やったりしてました。

uupaa.js のベースライブラリとなる、現在開発中の mofmof.js でも

  1. 日本語コメントを併記 してみたり
  2. 短さよりも、最適化と可読性のバランスを考慮したコードや、対称性を重視したコードに してみたり
  3. 経験を踏まえて、prototype拡張として実装するのが自然なものは、prototypeの下に置くべき とか考えなおしてみたり
  4. Titanium, NGCore, Windows 8最適化されるように ビルドオプション追加してみたり

などをやり始めています。

日本語コメントはこんな感じ

http://code.google.com/p/mofmof-js/source/browse/trunk/0.1/src/mofmof.js

はてなダイアリーだと、横幅が厳しい感じですね。

// mm.factory - Class and Nodes instance factory
function mm_factory(expr,   // @param ClassNameString/NodeQueryExpressionString/        // 引数: クラス名, Node検索文字列, Nodesインスタンス, Node, Nodeの配列
                            //        NodesInstance/Node/NodeArray:
                    arg1,   // @param Mix/Node/NodesInstance(= undefined):              // 引数: クラスインスタンス生成時の第一引数 または Nodes に渡すコンテキスト(省略可能)
                            //                          class arg1 or Nodes Context
                    arg2,   // @param Mix(= undefined): class arg2                      // 引数: クラスインスタンス生成時の第二引数(省略可能)
                    arg3,   // @param Mix(= undefined): class arg3                      // 引数: クラスインスタンス生成時の第三引数(省略可能)
                    arg4) { // @param Mix(= undefined): class arg4                      // 引数: クラスインスタンス生成時の第四引数(省略可能)
                            // @return ClassInstance/NodesInstance:                     // 戻り値: クラスインスタンス または Nodes インスタンス

    if (typeof expr === "string" && Class[expr]) {                                      // 文字列が指定され、それが mm.Class に登録済みならクラスインスタンスを生成する
        return new Class[expr](arg1, arg2, arg3, arg4);                                 // クラスインスタンスを生成し返す。適用される引数は最大で4つ
    }
    return new Nodes(expr, arg1);                                                       // Nodesインスタンスを生成し返す。適用される引数は最大で1つ
}

Prototype拡張はこんな感じに

http://code.google.com/p/mofmof-js/source/browse/trunk/0.1/src/object.js

上記のソースコードでは、Object, String, Number, Date, Array, Boolean, Function などに

  1. ECMAScript-262 5th 由来のもの
  2. Ruby 由来のもの
  3. JSON 由来のもの

を入れ込んでいます。

Prototype.js のように既存のネイティブコードを上書きするような事もありません。

// --- Object ---
// Object.keys()
// --- Array ---
// Array.isArray()      Array.toArray()     Array.range()
// Array#range()        Array#f()           Array#or()
// Array#and()          Array#fill()        Array#clean()
// Array#clear()        Array#clone()       Array#unique()
// Array#toHash()       Array#indexOf()     Array#lastIndexOf()
// Array#map()          Array#some()        Array#every()
// Array#filter()       Array#forEach()     Array#flatten()
// Array#reduce()       Array#reduceRight()
// --- Date ---
// Date.now()           Date#toJSON()
// --- Boolean ---
// Boolean#toJSON()
// --- Number ---
// Number.unique()      Number#has()        Number#pad()
// Number#clip()        Number#toJSON()     Number#inRange()
// Number#toHexString()
// --- Function ---
// Function#bind()      Function#build()
// --- String ---
// String#f()           String#has()        String#trim()
// String#trimTag()     String#trimQuote()  String#repeat()
// String#toHash()      String#toJSON()     String#sprintf()
// String#truncate()    String#toByteArray()
// --- JSON ---
// JSON.parse()         JSON.stringify()

2011-02-27

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

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

例えば、uu.ajaxGC部分では

    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だけを埋め込み、ブログやツイッターに読み物の形で説明する