WordPress Javascript コーディング基準 | WordPressのカスタマイズ

// より良い
var map = {
	ready: 9,
	when: 4,
	'you are': 15
};

// 小さいオブジェクトであれば無難
var map = { ready: 9, when: 4, 'you are': 15 };

// 悪い例
var map = { ready: 9,
	when: 4, 'you are': 15 };

array = [ a, b ];

foo( arg );

foo( 'string', object );

foo( options, object[ property ] );

foo( node, 'property', 2 );

// PHP規約との整合性のために
// 配列の表記においてキーの値に文字列または整数を使用する場合は両側にスペースは付加しない
prop = object['default'];
firstArrayElement = arr[0];

// 単独の引数としてのコールバック関数、オブジェクト、配列を持つ場合
// 引数の両側にはスペースは付加しない
foo(function() {
	// 文
});

foo({
	a: 'alpha',
	b: 'beta'
});

foo([
	'alpha',
	'beta'
]);

// 一つ目の引数としてのコールバック関数、オブジェクト、配列を持つ場合
// 一つ目の引数の前にはスペースは付加しない
foo(function() {
	// 文
}, options );

// 最後の引数としてのコールバック関数、オブジェクト、配列を持つ場合
// 最後の引数の後にはスペースは付加しない
foo( data, function() {
	// 文
});

var i;

if ( condition ) {
	doSomething( 'with a string' );
} else if ( otherCondition ) {
	otherThing({
		key: value,
		otherKey: otherValue
	});
} else {
	somethingElse( true );
}

// jQueryとは違いますが、WordPress では論理演算子NOT! の後にスペースを付加することを選択します。
// これもまた我々のPHP規約と一貫性を保つためです。
while ( ! condition ) {
	iterating++;
}

for ( i = 0; i < 100; i++ ) {
	object[ array[ i ] ] = someFn( i );
	$( '.container' ).val( array[ i ] );
}

try {
	// 式
} catch ( e ) {
	// 式
}

(function( $ ) {
	// インデントされた式

	function doSomething() {
		// インデントされた式
	}
})( jQuery );

var a, b, c;

if ( myFunction() ) {
	// 式
} else if ( ( a && b ) || c ) {
	// 式
} else {
	// 式
}

// これは悪い
var html = '<p>The sum of ' + a + ' and ' + b + ' plus ' + c
	+ ' is ' + ( a + b + c );

// 良い
var html = '<p>The sum of ' + a + ' and ' + b + ' plus ' + c +
	' is ' + ( a + b + c );

// 容認できる
var baz = ( true === conditionalStatement() ) ? 'thing 1' : 'thing 2';

// より良い
var baz = firstCondition( foo ) && secondCondition( bar ) ?
	qux( foo, bar ) :
	foo;

	if ( firstCondition() & secondCondition() &
			thirdCondition() ) {
		doStuff();
	}

elements
	.addClass( 'foo' )
	.children()
		.html( 'hello' )
	.end()
	.appendTo( 'body' );

// Good
var k, m, length,
	// ひとつのタブによりインデントされたその次の行
	value = 'WordPress';

// Bad
var foo = true;
var bar = false;
var a;
var b;
var c;

/* global passwordStrength:true */

(function( $ ) {
  // Expressions
})( jQuery );

// At the top of the file, set "wp" to its existing value (if present)
window.wp = window.wp || {};

someStatement();

// Explanation of something complex on the next line
$( 'p' ).doSomething();

/*
This is a comment that is long enough to warrant being stretched
over the span of multiple lines.
*/

function foo( types, selector, data, fn, /* INTERNAL */ one ) {
	// Do stuff
}

// 多くの重要な理由において、「 undefined 」「 null 」の両方の値をチェックする
if ( undefOrNull == null ) {
	// 式
}

var myStr = 'strings should be contained in single quotes';

// 文字列内では単一引用符をエスケープする:
'Note the backslash before the \'single quotes\'';

switch ( event.keyCode ) {

	// エンターキーとスペースキーのどちらもx() を起動する（フォールスルー）
	case $.ui.keyCode.ENTER:
	case $.ui.keyCode.SPACE:
		x();
		break;
	case $.ui.keyCode.ESCAPE:
		y();
		break;
	default:
		z();
}

function getKeyCode( keyCode ) {
	var result;

	switch ( event.keyCode ) {
		case $.ui.keyCode.ENTER:
		case $.ui.keyCode.SPACE:
			result = 'commit';
			break;
		case $.ui.keyCode.ESCAPE:
			result = 'exit';
			break;
		default:
			result = 'default';
	}

	return result;
}

var myArray = [];

var myArray = [ 1, 'WordPress', 2, 'Blog' ];

var myObj = {};

var myObj = new ConstructorMethod();

prop = object.propertyName;
prop = object[ variableKey ];
prop = object['default'];
prop = object['key-with-hyphens'];

if ( true === myCondition ) {
	// 行う事
}

// 良いし、能率的
var i, max;

// getItemCount() は一度だけ呼ばれる
for ( i = 0, max = getItemCount(); i < max; i++ ) {
	// 行う事
}

// 悪い　潜在的に能率が悪い:
// getItemCount() gets called every time
for ( i = 0; i < getItemCount(); i++ ) {
	// 行い
}

var obj = {
	first: 'thing 1',
	second: 'thing 2',
	third: 'lox'
};

var arr = _.chain( obj )
	.keys()
	.map(function( key ) {
		return key + ' comes ' + obj[ key ];
	})
	// Exit the chain
	.value();

// arr === [ 'first comes thing 1', 'second comes thing 2', 'third comes lox' ]

$tabs.each(function( index, element ) {
	var $element = $( element );

	// Do stuff to $element
});

Beautiful Syntax 美しい構文

A. 丸かっこ、中かっこ、改行

// if/else/for/while/try は常にスペース、中括弧、複数の行に架かるようにします。
// これは可読性を促進します。

if ( condition ) {
	// 文
}

while ( condition ) {
	//  文
}

for ( var i = 0; i < 100; i++ ) {
	// 文
}

// より良い例

var i,
	length = 100;
	
for ( i = 0; i < length; i++ ) {
	// 文
}

// または・・・

var i = 0,
	length = 100;

for ( ; i < length; i++ ) {
	// 文
}

var prop;

for ( prop in object ) {
	// 文
}

if ( true ) {
	// 文
} else {
	// 文
}

JavaScript

CopyExpand‹›

B. 割り当て、宣言、関数（名前、式、コンストラクター）

// 変数
// 注：WordPress Javascript Standardにおいては文字列は単一引用符を使用する
var foo = "bar",
	num = 1,
	undef;

// リテラル表記
var array = [],
	object = {};

// 可読性を促進するためにスコープ（関数）ごとに一つだけ 'var' を使用します
// 宣言するリストはすっきりしている状態を保ちます（同様に少ないキーストロークを守ります）

// 悪い例
var foo = "";
var bar = "";
var qux;

// 良い例
var foo = "",
	bar = "",
	quux;

// または
var // ここにコメントをつけます
foo = "",
bar = "",
quux;

// var 文は常にそれぞれのスコープ（関数）の最初になくてはなりません。
// ECMAScript 6 のlet もまた同様です。

// 悪い例
function foo() {

	// ここにいくつかの文を書きます

	var bar = "",
		qux;
}

// 良い例
function foo() {
	var bar = "",
		qux;

	// すべの文は変数の宣言の後に書きます
}

// 名前付きの関数の宣言
function foo( arg1, argN ) {

}

// 関数の使い方
foo( arg1, argN );

// 名前付きの関数の宣言
function square( number ) {
	return number * number;
}

// 関数の使い方
square( 10 );

// 不自然に続けて渡すスタイル
function square( number, callback ) {
	callback( number * number );
}

square( 10, function( square ) ) {
	// コールバック関数の文
});

// 式による関数の宣言
var square = function( number ) {

	// 値や関連する何かを返します
	return number * number;
};

// 識別子と式による関数の宣言
// この望ましい形はスタックトレースの中で自ら呼び出せる識別子を
// 持てる値が追加されます
var factorial = function factorial( number ) {
	if ( number < 2 ) {
		return 1;
	}

	return number * factorial( number-1 );
};

// コンストラクターの宣言
function FooBar( options ) {

	this.options = options;
}

// コンストラクターの使い方
var fooBar = new FooBar({ a: "alpha" });

fooBar.options;
// { a: "alpha" }

JavaScript

CopyExpand‹›‹›‹›

c. 例外や些細なこと

// コールバックと関数
foo(function() {
	// ここには実行される関数の最初の括弧と"function"との間には
	// スペースがないことを注意してください
});

// 配列を受け取る関数、スペースはなし
// WordPress Standard も同様
foo([ "alpha", "beta" ]);

// オブジェクトを受け取る関数、スペースなし
foo({
	a: "alpha",
	b: "beta"
});

//一つの文字列を受け取る場合、スペースなし
foo("bar");

// 中でグループ化された括弧、スペースなし
if ( ! ("foo" in obj) ) {

}

JavaScript

CopyExpand

D. 一貫性が常に勝つ
・・・省略・・・

E. クオート
あなたの好みがシングルクオートだろうとダブルクオートだろうとどうでもいい事です。これらはJavaScript の解析においては違いはありません。絶対に強制されることは一貫性につながります。同じプロジェクトの中でクオートを混ぜないでください。一つのスタイルを選び、それにこだわって下さい。

F. 行末と空行
スペースは読めない変更点を生み、差分を壊します。行末のスペースや空行のスペースを削除するためにコミット前の内容を組み込むかしっかり考えてください。

Type Checking (Courtesy jQuery Core Style Guidelines) 型のチェック

A. 実際の型
WordPress Javascript Coding Standard で既出 ≪ Type Checks 型チェック ≫を参照のこと

B. 強制された型
次の実装を考えて見てください。
こういうHTML があったとします。

<input type="text" id="foo-input" value="1">

// 'foo'は'0'という値で宣言されて、型は'number'になります。
var foo = 0;

// typeof foo;
// 'number'
・・・

// あなたのコードのどこかで、input要素から値を取得して
// 'foo'を更新する必要があります。

foo = document.getElementById("foo-input").value;

// もしあなたがこの時点で、'typeof foo' をテストした場合、次のような
// ロジックがあると、その結果は 'string' となることを意味します。
if ( foo === 1 ) {
	importantTask();
}
// 'importantTask()' はたとえ、'foo' が '1' だとしても評価されないでしょう。

//  + または - といった単項演算子を使って、強制的にこの問題を回避できます：
foo = +document.getElementById("foo-input").value;
// ^この + 演算子は右側の値をnumber に変換します。

// typeof foo;
// 'number"

if ( foo === 1 ) {
	importTask();
}
// こうすれば 'importTask()' は呼び出されます。

JavaScript

CopyExpand‹›

これらは同じように強制的に変換するいくつかの方法です。

var number = 1,
	string = "1",
	bool = false;

number;
// 1

number + "";
// "1"

string;
// "1"

+string;
// 1

+string++;
// 1

string;
// 2

bool;
// false

+bool;
// 0

boo + "";
// "false"

var number = 1,
	string ="1",
	bool = true;

string === number;
// false

string === number + "";
// true

+string === number;
// true

bool === number;
// false

+bool === number;
// true

bool === string;
// false

bool === !!string;
//true

var array = [ "a", "b", "c" ];

!!~array.indexOf("a");
//true

!!~array.indexOf("b");
//true

!!~array.indexOf("c");
//true

!!~array.indexOf("d");
//false

// 上記は”無駄に考え過ぎていないか”ということを考慮してください。
// 次のような indexOf が返した値を明確に比較するようなアプローチにしてみましょう。
if ( array.indexOf( "a" ) >= 0) {
	// ・・・
}

JavaScript

CopyExpand‹›‹›

var num = 2.5;

parseInt( num, 10 );

// これは次の場合と同じです
~~num;

num >> 0;

num >>> 0;

// どれも結果は2になります。
// しかし、負の値の場合は異なった扱いをされること覚えておきましょう。

var neg = -2.5;

parseInt( neg, 10 );

// これは次の場合と同じです。

~~neg;

neg >> 0;

// これはどれも-2になります。
// 一方で・・・

neg >>> 0;

// この結果は4294967294となります

JavaScript

CopyExpand

Conditional Evaluation 条件分の評価

// 配列の長さだけを評価する場合は次の代わりに：
if ( array.length > 0 ) ...

// このように評価すればいいでしょう：
if ( array.length ) ...

// 配列が空かどうかだけを評価する場合は次の代わりに：
if ( array.length === 0 ) ...

// このように評価すればいいでしょう：
if ( ! array.length ) ...

// 文字列が空では無い事だけを評価する場合は次の代わりに：
if ( string !== "" ) ...

// このようにすればいいでしょう：
if ( string ) ...

// 文字列がからであることだけを評価する場合は次のかわりに：
if ( string === "" ) ...

// このようにすればいいでしょう：
if ( ! string ) ...

// 参照先が true がどうかだけ評価する場合は次の代わりに：
if ( foo === true ) ...

// このように評価することを意味し、これは内部的な機能を利用します：
if ( foo ) ...

// 参照先が false かどうかを評価する場合は次の代わりに：
if ( foo === false ) ...

// 強制的に true の評価を行うために否定を使います
if ( ! foo ) ...

// 注意点としてこの場合は、""、null、undefined、NaN といった値にも
// マッチします。もし false に限定する必要があるのであれば次のようにします
if ( foo ===false ) ...

// 参照先が false、""、0 ではなく、null または undefined かどうかだけを
// 評価する場合は次の代わりに：
if ( foo === null || foo === undefined ) ...

// 次のように == を使用して型の変換を利用します
if ( foo == null ) ...

// == は false 、""、0 ではなく null と undefined の両方を null とマッチすることを
// 覚えておいてください
null == undefined

JavaScript

CopyExpand‹›

常にベストで正確な結果のための評価をしましょう - 上記はガイドラインであって、ドグマではありません。
注：ドグマとは・・・1.宗教上の教義。2.独断的な説。

// 型の変換と評価の注意書き
// '==' よりも '===' を選びましょう（ルーズな型の評価が必要でない限り）
// === は次のように型を変換しません：

"1" === 1;
// false

// == は次のように型を変換します：

"1" == 1;
// true

// ブール値、true な値と false な値が
// ブール値:
true,false

// true な値:
"foo",1

// false な値:
"", 0, null, undefined, NaN, void 0

JavaScript

CopyExpand

Practical Style 実際のスタイル

// 実際のモジュール

(function( global ) {
	var Module = (function() {

		var data = "secret";
	
		return {
			// 何かのブール値のプロパティ
			bool: true,
			// 何かの文字列の値
			string: "a string",
			// 配列のプロパティ
			array: [ 1, 2, 3, 4 ],
			// オブジェクトのプロパティ
			object: {
				lang: "en-Us"
			},
			getData: function() {
				// 現在の 'data' の値を取得する
				return data;
			},
			setData: function( value ) {
				// 'data' の値をセットしてそれを返す
				return ( data = value );
			}
		};
	})();
	
	// に可能性のあるものはここに
	
	// グローバルオブジェクトにモジュールを見えるようにします
	global.Module = Module;
})( this );

// 実際のコンストラクター

(function( global ) {

	function Ctor( foo ) {
		this.foo = foo;

		return this;
	}

	Ctor.prototype.getFoo = function() {
		return this.foo;
	};

	Ctor.prototype.setFoo = function( val ) {
		rerutn ( this.foo = val );
	};

	// 'new' を使わずにコンストラクターを呼び出すにはこのようにします：
	var ctor = function( foo ) {
		return new Ctor( foo );
	};

	// グローバルオブジェクトにモジュールを見えるようにします
	global.ctor = ctor;

})( this );

JavaScript

CopyExpand

Misc 雑則

このセクションは偏見的と見なされるべきではないアイデアやコンセプトを説明する代わりに、一般的なプログラミングタスクを行うためのより良い方法を見つけるためのプラクティスを助長するものです。

A. switch の使用はできるだけ避けるべきでモダンなメソッドトレースは switch 文をブラックリストの関数にするでしょう。

// switch 文の例
switch( foo ) {
	case "alpha":
		alpha();
		break;
	case "beta":
		beta();
		break;
	default:
		// デフォルトのための何か
		break;
}

// オブジェクトリテラルやモジュールを利用したより良いアプローチ
var switchObj = {
	alpha: function() {
		// 文
		// 返り値
	},
	beta: function() {
		// 文
		// 返り値
	},
	_default: function() {
		// 文
		// 返り値
	}
}

var switchModule = (function() {
	return {
		alpha: function() {
			// 文
			// 返り値
		},
		beta: function() {
			// 文
			// 返り値
		},
		_default: function() {
			// 文
			// 返り値
		}
	};
})();

// もし、'foo' が 'switchObj' または 'switchModule' のプロパティならメソッドとして実行されます。

( Object.hasOwnProperty.call( switchObj, foo ) && switchObj[ foo ] || switchObj._default )( args );

( Object.hasOwnProperty.call( switchObj, foo ) && switchModule[ foo ] || switchModule._default )( args );

// もし、'foo' の値がはっきり分かっているなら、OR のチェックを省いて
// 実行部分だけ残すようにできます。

switchObj[ foo ]( args );
switchModule[ foo ]( args );

// このパターンはコードの再利用性を促進します。

JavaScript

CopyExpand‹›

B. ごくわずかなパフォーマンスと早く返り値を返すことでコードの可読性を促進します。

// 悪い例
function returnLate( foo ) {
	var ret;

	if ( foo ) {
		ret = "foo";
	} else {
		ret = "quux";
	}
	return ret;
}

// 良い例
function returnEarly( foo ) {
	if ( foo ) {
		return "foo";
	}
	return "quux";
}

JavaScript

CopyExpand

Naming ネーミング

A. あなたがコードをコンパイルしたり圧縮したりするわけではないので、そういった事をしようとしてはいけません。
次のコードはひどいネーミングの例です。

function q( s ) {
	return document.querySelectorAll(s);
}
var i,a=[],els=q("#foo");
for(i=0;i<else.length;i++){a.push(els[i]);}

JavaScript

CopyExpand

まぎれもなくこう書いた方がいいでしょう。
これはロジックは同じですが、より親切で考えられたネーミングです（そして読みやすい構造になっています。）：

function query( selector ) {
	return document.querySelectorAll( selector );
}

var idx = 0,
	elements = [],
	matches = query("#foo"),
	length = matches.length;
	
for ( ; idx < length; idx++ ) {
	elements.push( matches[ idx ] );
}

JavaScript

CopyExpand

ネーミングの観点でいくつか補足すると

// 文字列のネーミング
 'dog'　は文字列です。
 
 // 配列のネーミング
 'dogs' は 'dog' という文字列の配列です
 
 // 関数、オブジェクト、インスタンスなどのネーミング
 camelCase; function と var による宣言
 
 // コンストラクターやプロトタイプなどのネーミング
 PascalCase; コンストラクター
 
 // 正規表現のネーミング
 rDesc = //;
 
 // Google Closure Library Style Guide より
 
 functionNamesLikeThis;
 variableNamesLikeThis;
 ConstructorNamesLikeThis;
 EnumNamesLikeThis;
 methodNamesLikeThis;
 SYMBOLIC_CONSTANTS_LIKE_THIS;

JavaScript

CopyExpand

B. this の扱い
後から呼び出される BoundFunction を定義する場合は call や apply の一般的な使われ方よりも .bind( this ) や同等の機能が好ましいです。好ましいオプションがない場合だけ、別の方法を考えましょう。

function Device( opts ) {
 
 	this.value = null;
 
 	// これは非同期のストリームをオープンし
 	// 継続的に呼び出されます
 	stream.read( opts.path, function( data ) {
 
 		// このインスタンスの現在の値を
 		// データストリームの最新の値で更新します
 		this.value = data;

	}.bind(this) );

	// デバイスのインスタンスから頻繁に発行される
	// イベントを絞ります
	setInterval(function() {

		// 絞ったイベントを発行します
		this.emit("event");

	}.bind(this), opts.freq || 100 );
}

// EventEmitter を継承したかのように装います ;)

JavaScript

CopyExpand

もし利用できない場合でも最近の多くのJavaScript ライブライには .bind と同様な機能があります。

// 例）lodash/underscore の _.bind()
function Device( opts ) {

	this.value = null;

	stream.read( opts.path, _.bind(function( data ) {
		this.value = data;
	}, this) );
	setInterval(_.bind(function() {
		this.emit("event");
	}, this), opts.freq || 100 );
}

// 例）jQuery.proxy
function Device( opts ) {
	this.value = null;
	stream.read( opts.path, jQuery.proxy(function( data ) {
		this.value = data;
	}, this) );
	setInterval( jQuery.proxy(function() {
		this.emit("event");
	}, this), opts.freq || 100 );
}

// 例）dojo.hitch
function Device( opts ) {
	this.value = null;
	stream.read( opts.path, dojo.hitch( this, function( data ) {
		this.value = data;
	}) );
	setInterval( dojo.hitch( this, function() {
		this.emit("event");
	}), opts.freq || 100 );
}

JavaScript

CopyExpand

最後の回避方法は、識別子として this への別名に self を使うことですが、これは極端なバグになる傾向があるため、可能な限り避けるべきです。

function Device( opts ) {
	var self = this;
	this.valu = null;
	stream.read( opts.path, function( data ) {
		self.value = data;
	});
	setInterval(function() {
		self.emit("event");
	}), opts.freq || 100 );
}

JavaScript

CopyExpand

C. thisArg を使う
ES 5.1の各プロトタイプのメソッドでは特別な thisArg という署名に対応しています。これは可能な限り利用するべきです。

var obj;
obj = { f: "foo", b: "bar", q: "qux" };
object.keys( obj ).forEach(function( key ) {
	// |this| は 'obj' への参照
	console.log( this[ key ] );
}, obj );// <-- 最後の引数が 'thisArg'
// 結果は・・・

// "foo"
// "bar"
// "qux"

JavaScript

CopyExpand

thisArg は Array.prototype.every 、Array.prototype.forEach 、Array.prototype.some 、Array.prototype.map 、Array.prototype.filter と一緒に利用できます。