Skip to content

ModuleName

Jump to bottom Edit New page
uupaa edited this page May 31, 2015 · 19 revisions

このエントリでは WebModule の命名制約について説明します。

WebModule の命名には制約があります。
この制約は、WebModule が GitHub と npm という2つの異なるポリシーを持った環境にモジュールを登録する都合から発生しています。

  • 使用可能な文字種の違い
    • GitHub リポジトリ名に使用できる文字種は、A-Z, a-z, 0-9, ドット(.), アンダーバー(_), ハイフン(-) です
    • npm パッケージ名に使用できる文字種は、a-z, 0-9, ドット(.), アンダーバー(_) です
文字種 GitHub リポジトリ名 npm パッケージ名
A-Z YES NO
a-z YES YES
0-9 YES YES
.(ドット) YES YES
_(アンダーバー) YES YES
-(ハイフン) YES NO
  • 名前空間の違い
    • GitHub はユーザごとのローカルな名前空間でモジュールを管理しています。各ユーザが思い思いに MyExample.js を作成できます
    • npm はグローバルな名前空間でモジュールを管理しています。あるユーザが myexample.js を作成すると、もうその名前は使用できません。先願制です

これらを踏まえ、WebModule の命名規則は以下のようになっています。

WebModule の命名規則

WebModule のモジュール名は、MyExample.js のように、プリフィクス("My") + 機能名("Example") + 拡張子(".js") で構成されます。

  • プリフィクスは短く、ユニークな文字列を付けてください
    • 省略も可能可能ですが、特殊な事情がない限り付けてください(RECOMMENDED)
    • 省略した場合は、JavaScript の global 空間における衝突が発生する可能性があります
  • 機能名にはモジュールの機能性を表す文字列を付けてください
    • PacalCase で命名してください
    • iPhone や AKB などの広く一般に認識されている単語や略語は無理に加工せずそのまま利用します(例: MyiPhoneDevice.js, MyAKBMemberList.js)
  • 拡張子には開発環境を示す拡張子を指定します
    • JavaScript なら ".js" にします。TypeScript なら ".ts" にします。
    • npm の説明には「パッケージ名の末尾に".js"をつける必要はありません」といった説明がありますが、気にせず付けてください
      • 拡張子を付けておくことで開発言語の特定が簡単になります。これは将来 WebModule が JavaScript 以外の環境(たとえばTypeScript)をサポートした場合に重要になります
      • GitHub リポジトリ名から npm パッケージ名を生成する式が簡単になります
        • "uupaa/MyExample.js".replace("/", ".").toLowerCase(); // -> "uupaa.myexample.js"

命名例

WebModule のモジュール名を "MyExample.js" とした場合を例に説明します。

GitHub のリポジトリ作成画面で指定するリポジトリ名を "MyExample.js" とします。

Owner                    Repository name
+-------------------+   +-------------------+
| uupp              | / | MyExample.js      |
+-------------------+   +-------------------+

この状態で node ../WebModule/run/setup コマンドを実行すると、このような package.json が生成されます。

{
  "name": "uupaa.myexample.js",
  "url":  "https://github.com/uupaa/MyExample.js",
  "repository": {
    "type": "git",
    "url":  "https://github.com/uupaa/MyExample.js.git"
  },
  ...
}

npm publish コマンドで npm に登録されるパッケージ名は uupaa.myexample.js になります。

MyExample.js モジュールについてまとめると、以下のようになります。

名前
GitHub ユーザ名 uupaa
WebModule 名 MyExample.js
GitHub リポジトリ名 uupaa/MyExample.js
またはユーザ名を省略し MyExample.js
GitHub リポジトリURL https://github.com/uupaa/MyExample.js
npm パッケージ名 uupaa.myexample.js
script パス <script src="lib/MyExample.js">
require パス require("lib/MyExample.js")
インスタンス化 new MyExample()

npm 名前空間内における名前の衝突について

WebModule で生成した npm 名前空間用のパッケージ名(例: uupaa.myexample.js)には 強制的に GitHub ユーザ名を付与した形にしています。 これにより npm のグローバルな名前空間におけるパッケージ名の衝突はほぼ回避できます。

JavaScript の global 空間内における名前の衝突について

モジュールのプリフィクスを省略したり、他のユーザが利用しているプリフィクスと同じものを使うと、JavaScript クラス名が衝突してしまいます。

<script src="foo.myexample.js"></script> <!-- window.MyExample = function MyExample() {} -->
<script src="bar.myexample.js"></script> <!-- window._MyExample = function MyExample() {} -->
<script src="buz.myexample.js"></script> <!-- window._MyExample = function MyExample() {} -->

var example = new MyExample();

既存のプリフィクスは、 npm search WebModule コマンドで検索可能です。

Add a custom footer
Clone this wiki locally