スキップしてメイン コンテンツに移動

僕のWeb開発の、変数と関数、ファイル名とフォルダ名の命名ルール

俺々命名ルールについてです。

  1. 前提
  2. ファイル名とフォルダ名の命名
    1. プロジェクトフォルダの例
    2. js scss ファイル名とフォルダ名に数字をつける
    3. ドットをフォルダ名の頭に
    4. .generated フォルダと .generated ファイル
    5. README.md をなるべく全ての階層に用意する
  3. 変数と関数の命名
    1. グローバル空間
      1. グローバル空間に公開するオブジェクトの例
      2. グローバル空間に宣言する定数
      3. グローバル空間に宣言する Closure Compiler の @define
    2. パッケージのグローバル
    3. モジュールのグローバル
    4. モジュール下のプライベート空間

1. 前提

  1. Google Closure Compiler でコンパイルします。
  2. import 文を使った他モジュールの参照をしません。モジュールバンドラーも使いません。コンパイル結果が開発中のコードと飛躍しないように、自作の gulp プラグイン gulp-diamond-princess-zoning で javascript ファイルを一本化しています。

2. ファイル名とフォルダ名の命名

2.1. プロジェクトフォルダの例

.artwork/
.psd ファイルなどを入れておく
.generated/
プロジェクトフォルダ下のビルドツールを走らせた結果得られる生成物を入れる。
.submodules/
git の submodule はこの下に配置する。通常の作業時に視界に入れない為。
js-buildtools/
プロジェクトの為に書かれたビルドツールの置き場所。僕の場合は gulp プラグインが入る。
node-modules/
プロジェクトが依存する npm パッケージ
src/
ソースファイルの置き場所
html-templete/
HTML テンプレートファイルの置き場所。
js/
メインの javascript ファイルの置き場所。
js-common/
ビルドツール、メインの javascript、インラインの javascript、serviceworker で共通のコードの置き場所。
js-externs/
externs.js の置き場所。
js-inline/
ビルドタスクによって html ファイルに埋め込まれるインライン javascript ファイルの置き場所。
js-serviceworker/
serviceworker 用 javascript のソースファイルの置き場所。
scss/
SCSS ファイルの置き場所。SMACSS 等を参考にフォルダとファイルを整理します。

2.2. js scss ファイル名とフォルダ名に数字をつける

数字を添えて、ファイルが実行される順番にファイルとフォルダが並ぶようにする。ファイルやフォルダが追加された場合は頻繁にファイル名とフォルダ名を変更する。

また gulp-diamond-princess-zoning ではファイル名の辞書順にファイルを処理していく。

2.3. ドットをフォルダ名の頭に

開発時に触れる頻度の少ないフォルダには . を付けてプロジェクトフォルダ階層の先頭に集める。開発中に視界に入りづらくする。

2.4. .generated フォルダと .generated ファイル

ビルドツールによって生成されるファイルには .generated または _generated をファイル名に付与して開発対象ファイルと区別する。.generated なファイルからなるフォルダの名前にも .generated を付与する。

gulp では . で始まるファイル名のファイルを無視する為、_generated を適宜に使用する。

2.5. README.md をなるべく全ての階層に用意する

階層の README.md ファイルにフォルダとファイルの説明を書く。各フォルダ階層の README.md ファイルをハイパーリンクで参照するようにする。

2. 変数と関数の命名

パッケージ(プロジェクトとほぼ同意)、モジュール、グローバル変数、パッケージのグローバル変数、モジュールのグローバル変数といった名称については、僕の書いた gulp プラグイン gulp-diamond-princess-zoning の README.md を参照します。

2.1. グローバル

3.1.1. グローバルに公開するオブジェクトの例

window.app = app;

var Debug = { log : function( message ){} };

Closure Comoiler による名前の短縮から保護する為、js-externs/externs.js ファイルに追記すること。

3.1.2. グローバルに宣言する定数

パッケージに固有の接頭辞も付けておく。パッケージに固有の接頭辞に続けてアンダースコアを2つ繋げる。 

var MY_COMMON_PROJECT__EVENT_CLICK = 1,
    MY_COMMON_PROJECT__EVENT_FOCUS = 2;

Closure Compiler の advanced コンパイルによってコードに埋め込まれるので、グローバル空間に変数が追加されることは無い。

3.1.3. グローバル空間に宣言する Closure Compiler の @define

DEFINE_ を接頭辞に付ける。@define は、ビルド時に定数に値を埋め込む Closure Compiler のオプションです。

複数のパッケージを組み合わせる場合、パッケージに固有の接頭辞も付けておく。パッケージに固有の接頭辞に続けてアンダースコアを2つ繋げる。 

/** @define {boolean} */
var DEFINE_MY_COMMON_PROJECT__DEBUG = true;

Closure Compiler のバージョンによっては、var 宣言とコメントの位置関係でエラーが起きる場合があった。その場合は次のように記述して回避した。 

var
  /** @define {boolean} */
  DEFINE_MY_COMMON_PROJECT__DEBUG = true;

3.2. パッケージのグローバル空間

変数名や関数名を p_ から始める。

複数のパッケージでパッケージグローバル空間を共有する想定のパッケージはパッケージに固有の接頭辞とアンダースコア2つを付けて p_MY_COMMON_PROJECT__XXXXXX とする。 

var p_XXXXXX = 1;
var p_MY_COMMON_PROJECT__XXXXXX = "";

3.3. モジュールのグローバル空間

変数名や関数名を m_ から始める。

gulp-diamond-princess-zoning のwrapAll を有効にして得た出力をコンパイルすると、モジュールのグローバル空間に正しく定義されているか？を確認出来ます。 

var m_XXXXXX = 1;

3.4. モジュール下のプライベート空間

モジュール内で名称がバッティングしないように冗長な名前にします。例えばファイル名を頭に付けます。このルールで命名された変数や関数は同一ファイル内でしか参照しないようにします。 

var AjaxByXHR_apis = {};

function AjaxByXHR_post(){};
, 編集
コメントを投稿