[翻訳] Riotjs Style Guide

[De Voorhoede](https://twitter.com/devoorhoede)社のRiotJS スタイルガイドです。パブリックドメインとして公開されています。

https://github.com/voorhoede/riotjs-style-guide

Riotjsに出会い、参考になりそうなスタイルガイドをさがしていたところ、こちらのスタイルガイドを発見したので、自分の理解のために翻訳しました。jsの理解、Riotjsの理解、翻訳どれも未熟な部分があります。編集リクエスト歓迎です :bow:
Riotjsは日本語のドキュメントが少ないと言われているそうなので、何かの参考になれば幸いです。
以下翻訳

---

# RiotJS スタイルガイド
De Voorhoede独断 チームのための RiotJS スタイルガイド

[![RiotJS Style Guide badge](https://cdn.rawgit.com/voorhoede/riotjs-style-guide/master/riotjs-style-guide.svg)](https://github.com/voorhoede/riotjs-style-guide)

## Purpose 目的
このスタイルガイドを利用すると、[RiotJS](http://riotjs.com/) に構造を持たせることができます。

RiotJSのコードを...

* 開発者・チームメンバーにとって理解しやすく・探しやすくします
* IDEにとって解釈しやすく・補助しやすくします
* すでに取り入れられているビルドツールを使いやすくします
* バンドルされたコードを分けて管理しやすくします

このスタイルガイドはJohn Papaによる[AngularJS Style Guide](https://github.com/johnpapa/angular-styleguide)にインスパイアされています。

## デモ

[RiotJS demos](https://github.com/voorhoede/riotjs-demos#riotjs-demos-) はこのガイドラインに沿った実用的なサンプル集です。

## 目次
[モジュールベースの開発](#モジュールベースの開発)
[タグモジュールのネーミング](#タグモジュールのネーミング)
[1モジュール=1ディレクトリ](#1モジュール=1ディレクトリ)
[*.tag.htmlを使う](#*.tag.htmlを使う)
[タグ内で`<script>`を使う](#タグ内で<script>を使う)
[タグのテンプレート変数はシンプルに](#タグのテンプレート変数はシンプルに)
[タグのオプションはプリミティブに](#タグのオプションはプリミティブに)
[タグオプションを設定する](#タグオプションを設定する)
[thisをtagにアサインする](#thisをtagにアサインする)
[タグのプロパティとメソッドを一番最初に書く](#タグのプロパティとメソッドを一番最初に書く)
[ES6風シンタックスを避ける](#ES6風シンタックスを避ける)
[tag.parentは避ける](#tag.parentは避ける)
[each...inシンタックスを使う](#each...inシンタックスを使う)
[スタイルは外部ファイルに置く](#スタイルは外部ファイルに置く)
[タグ名をスタイルスコープとして使う](#タグ名をスタイルスコープとして使う)
[自分のタグAPIをドキュメント化する](#自分のタグAPIをドキュメント化する)
[タグのデモを追加する](#タグのデモを追加する)
[タグファイルをlintする](#タグファイルをlintする)
[プロジェクトにバッジをつける](#プロジェクトにバッジをつける)

## モジュールベースの開発
アプリは常に、1つのことをちゃんとやる小さなモジュールで構成すること。

1モジュールはアプリ内の小さな自己完結したパーツです。RiotJSのマイクロフレームワークは特に *タグ* と呼ばれる *ビュー・ロジック モジュール* を作成するために設計されています。

### Why？

小さいモジュールのほうが、学ぶのも、理解するのも、メンテナンスするのも、再利用するのも、デバッグするのも簡単だからです。自分にとっても、他の開発者にとっても。

### How?

すべてのriotタグは（モジュールのように） [FIRST](https://addyosmani.com/first/)であるべきです。つまり、[責務が1つ](https://en.wikipedia.org/wiki/Single_responsibility_principle)で、独立していて、再利用できて、小さくて、テスタブルであるべきです。

もしモジュールが多くなりすぎた、あるいは大きくなりすぎたというときには、一つのことだけを行うより小さなモジュールに分割しましょう。
おおまかなやり方として、1つのタグファイルの行数を100未満にしましょう。
自分の書いたタグモジュールが独立して動くかどうか、スタンダローンデモで確かめましょう。

**ヒント** もしAMDかCommonJS module loaderを使っていたら、`--modular` フラグをつけることでタグをコンパイルできます。

```base
# AMDとCommonJSを有効にする
riot --modular
```

[↑ 目次に戻る](#目次)


## タグモジュールのネーミング
タグモジュールとは、Riotタグを含む特定のモジュールのタイプのことです。

タグモジュールは

* **意味がある名前**:  具体的すぎず、抽象的すぎない名前
* **短い名前**: 2，3語で構成された名前
* **発音できる名前**: タグについて話し合いたいので発音できる名前

であるべきです。

さらに以下の条件を満たすものであるべきです。

* **カスタム要素仕様に準拠する** : 必ずハイフンを含む、予約語を使わない。
* **`app-` というネームスペースを使う** : 非常に包括的で、それ以外だと1語になってしまう場合にも他のプロジェクトで簡単に再利用できるため。


### Why?

* 名前は、モジュールについて話し合うときに使われます。そのため、短く、意味があり、発音できる名前であるべきです。
* タグ要素はDOMに挿入されます。そのため仕様に忠実であるべきです。

### How?

```html
<!-- recommended -->
<app-header />
<user-list />
<range-slider />

<!-- avoid -->
<btn-group /> <!-- 短いけど、発音できません。代わりに `button-group` としましょう-->
<ui-slider /> <!-- すべてのタグはUI要素なので、`ui-` に意味はありません-->
<slider /> <!--  カスタムエレメントの仕様に準拠していません-->
```

[↑ 目次に戻る](#目次)

## 1モジュール = 1ディレクトリ
1モジュールを構成するファイルを1つにまとめて1箇所に置きましょう。

### Why?

モジュールファイル(Riotタグ、テスト、アセット、ドキュメントなど)をまとめることで、見つけやすく、移動しやすく、再利用しやすくするため。

### How?

ディレクトリ名、ファイルのベース名をモジュール名と同じにしましょう。
ファイルの内容によって拡張子を変更します。

```
modules/
└── my-example/
    ├── my-example.tag.html
    ├── my-example.less
    ├── ...
    └── README.md
```

If your project uses nested structures, you can nest a module within a module.
For example a generic `radio-group` module may be placed directly inside "modules/". While `search-filters` may only make sense inside a `search-form` and may therefore be nested:

もしプロジェクトでネスト構造をつかっているなら、モジュールの中にモジュールをネストしてもいいでしょう。
例えば包括的な `radio-group` モジュールを `modules/` ディレクトリの中に置きます。 `search-filters` を `search-form` の中に置くと、こんなふうにネストされます。

```
modules/
├── radio-group/
|   └── radio-group.tag.html
└── search-form/
    ├── search-form.tag.html
    ├── ...
    └── search-filters/
        └── search-filters.tag.html
```

[↑ 目次に戻る](#目次)

##  `*.tag.html` を使う

Riotは *タグ*と呼ばれる新しいコンセプトを提唱していて、 `*.tag` 拡張子を使うことが推奨されています。しかし、本質的にはタグはマークアップを含むカスタム要素です。その為、 `*.tag.html` 拡張子を使いましょう。

### Why?
* 開発者に、ただのHTMLではなくてRiotのタグ要素であると知らせるため。
* IDEの補助を向上させるため（どのように解釈すればいいか伝えるため）。

### How?

 [in-browser compilation](http://riotjs.com/guide/compiler/#in-browser-compilation)の場合。

```html
<script src="path/to/modules/my-example/my-example.tag.html" type="riot/tag"></script>
```

 [pre-compilation](http://riotjs.com/guide/compiler/#pre-compilation)の場合、 [custom extension](http://riotjs.com/guide/compiler/#custom-extension)を設定します。

```bash
riot --ext tag.html modules/ dist/tags.js
```

 [Webpack tag loader](https://github.com/srackham/tag-loader)を使っている場合は、拡張子に合うように [loaderを設定しましょう。](http://webpack.github.io/docs/using-loaders.html#configuration)

```javascript
{ test: /\.tag.html$/, loader: 'tag' }
```

[↑ 目次に戻る](#目次)

## タグ内で `<script>` を使う

Riotではタグ要素のなかに[`<script>`タグ抜きで](http://riotjs.com/guide/#no-script-tag)JavaScriptを書くことができますが、 **常に`<script>`を使うべきです** 。こちらのほうがWeb標準に近いし、開発者やIDEの混乱を防ぎます。

### Why?
* マークアップがスクリプトとして解釈されるのを防ぐため。
* IDEのサポートを向上させるため（どのように解釈するか知らせるため）。
* 開発者にどこまでがマークアップでどこからがスクリプトか知らせるため。

### How?

```html
<!-- recommended -->
<my-example>
	<h1>The year is { this.year }</h1>

	<script>
		this.year = (new Date()).getUTCFullYear();
	</script>
</my-example>

<!-- avoid -->
<my-example>
	<h1>The year is { this.year }</h1>

	this.year = (new Date()).getUTCFullYear();
</my-example>
```

[↑ 目次に戻る](#目次)

## タグのテンプレート変数はシンプルに

Riotの[テンプレート変数](http://riotjs.com/guide/#expressions)は100％ JavaScriptです。そのため非常に強力ですが、ひどく複雑になることもあります。タグのテンプレート変数はシンプルに保ちましょう。

### Why?

* 複雑なテンプレート変数は難しすぎて読めないから。
* テンプレート変数は他の場所で再利用できないから。コードの重複と腐敗を招く。
* 一般的にIDEはテンプレート変数のシンタックスはサポートしていないので、オートコンプリートやバリデートができないから。

### How?

複雑な表現はタグメソッドかタグプロパティに移動しましょう。

```html
<!-- recommended -->
<my-example>
	{ year() + '-' + month() }

	<script>
		const twoDigits = (num) => ('0' + num).slice(-2);
		this.month = () => twoDigits((new Date()).getUTCMonth() +1);
		this.year  = () => (new Date()).getUTCFullYear();
	</script>
</my-example>

<!-- avoid -->
<my-example>
	{ (new Date()).getUTCFullYear() + '-' + ('0' + ((new Date()).getUTCMonth()+1)).slice(-2) }
</my-example>
```

[↑ 目次に戻る](#目次)

## タグのオプションはプリミティブに

Riotではタグ要素の属性を使ってタグインスタンスにオプションを渡せます。タグインスタンスのオプションには  `opts` を経由してアクセスできます。
例えば  `<my-tag my-attr="{ value }" />`の`my-attr`の値は、`my-tag` に `opts.myAttr`を使うことでアクセスできます。

Riotでは属性を経由して複雑なJavaScriptオブジェクトを渡すことができますが、 **タグオプションは出来る限りプリミティブ値にしておくこと** を心がけるといいでしょう。 [JavaScript primitives](https://developer.mozilla.org/en-US/docs/Glossary/Primitive) と関数のみを使ってみましょう。複雑なオブジェクトは避けます。

このルールには例外があります。オブジェクト（コレクションや再帰的なタグ）を使って問題を解決するときや、アプリの中でもよく知られてるオブジェクト（ウェブショップのオブジェクト）の場合です。

### Why?

* それぞれのオプションで属性を分けることで、タグが明確で表現的なAPIを持つようになるから。
* オプションの値にJava Scriptのプリミティブ値と関数のみを使うことで、タグのAPIがネイティブなHTML(5)の要素に近くなるから。カスタム要素に直接触れるようになるから。
* それぞれのオプション値に属性を使うことで、他の開発者もタグインスタンスに渡るものが何なのか、簡単に理解できるから。
* 複雑なオブジェクトを渡してしまうと、オブジェクトのどのプロパティとメソッドが実際にカスタムタグで使われているのか見えなくなるから。リファクタリングしづらくなるし、コードの腐敗を招く。

### How?

1つのオプションに1つのタグ属性を利用しましょう。プリミティブ値または関数を使いましょう。


```html
<!-- recommended -->
<range-slider
	values="[10, 20]"
	min="0"
	max="100"
	step="5"
	on-slide="{ updateInputs }"
	on-end="{ updateResults }"
	/>

<!-- avoid -->
<range-slider config="{ complexConfigObject }">
```
```html
<!-- exception: recursive tag, like menu item -->
<menu-item>
	<a href="{ opts.url }">{ opts.text }</a>
	<ul if="{ opts.items }">
		<li each="{ item in opts.items }">
			<menu-item
				text="{ item.text }"
				url="{ item.url }"
				items="{ item.items }" />
		</li>
	</ul>
</menu-item>
```

[↑ 目次に戻る](#目次)

## タグオプションを設定する

Riotではタグオプションが自分のAPIになります。堅牢で推測しやすいAPIなら他の開発者も自分の作ったタグをかんたんに使えるようになります。

タグオプションはHTMLカスタム属性を経由して渡されます。属性の値はRiotの表記 (`attr="{ var }"`)かプレーン文字列 (`attr="value"`)で書かないと消えてしまします。タグオプションを制御することでこれらいろいろなケースを許容することができます。

## Why?

タグオプションを制御することでタグがいつでも動くようになります（セキュアプログラミング）。他の開発者が想定外の方法でタグを利用したとしても、動きます。

## How?

* オプション値にデフォルト値を入れる。
* オプションに期待される型が入るように型変換する。
* タグを利用する前にオプションがあるかどうかチェックする。

例えば[Riotの todo example](http://riotjs.com/guide/#example)にデフォルト値を入れると、 `item` がなくても動くようになります。

```javascript
this.items = opts.items || []; // default to empty list
```

他の場合でも動くかどうか確認しましょう。

```html
<todo items="{ [{ title:'Apples' }, { title:'Oranges', done:true }] }"> <!-- uses given list -->
<todo> <!-- uses empty list -->
```

[keep tag options primitive](https://github.com/voorhoede/riotjs-style-guide#keep-tag-options-primitive)  の`<range-slide>` タグは `min`, `max`, `step` オプションに数値が入ります。型変換を使いましょう。

```javascript
// if step option is valid, use as number otherwise default to one.
this.step = !isNaN(Number(opts.step)) ? Number(opts.step) : 1;
```

違う値でも動くことを確認しましょう。

```html
<range-slider> <!-- uses default -->
<range-slider step="5"> <!-- converts "5" to number 5 -->
<range-slider step="{ x }"> <!-- tries to use `x` -->
```

 `<range-slider>` はオプションとして `on-slide`と `on-end` コールバックをサポートしています。オプションがあるかどうか、想定するフォーマットかどうか、事前に確認しましょう。

```javascript
slider.on('slide', (values, handle) => {
	if (typeof opts.onSlide === 'function') {
		opts.onSlide(values, handle);
	}
}
```

違う値でも動くかどうか確認しましょう

```html
<range-slider> <!-- does nothing -->
<range-slider on-slide="{ updateInputs }"> <!-- calls updateInputs on slide -->
<range-slider on-slide="invalid option"> <!-- does nothing -->
```

[↑ 目次に戻る](#目次)

##  `this`を`tag`にアサインする

Riotタグ要素のコンテキストでは、 `this` は [tag instance](http://riotjs.com/api/#tag-instance)に紐付きます。
そのため、他のコンテキストで利用する場合には`this`を`tag`として使えるようにしましょう。

### Why?

* `this`を`tag`という変数に代入することで、他の開発者たちに [tag instance](http://riotjs.com/api/#tag-instance) と紐付けられていることを示すため。

### How?

```javascript
/* recommended */
// ES5: assign `this` to `tag` variable
var tag = this;
window.onresize = function() {
    tag.adjust();
}

// ES6: assign `this` to `tag` constant
const tag = this;
window.onresize = function() {
    tag.adjust();
}

// ES6: you can still use `this` with fat arrows
window.onresize = () => {
    this.adjust();
}

/* avoid */
var self = this;
var _this = this;
// etc
```

[↑ 目次に戻る](#目次)

## タグのプロパティとメソッドを一番最初に書く

普通はRiotタグの中に一番最初にマークアップを書いて、その後スクリプトを書きます。 スクリプト内のtag (`this`)にひもづいたプロパティとメソッドは直接マークアップで参照できます。スクリプトの最初にこれらのタグのプロパティとメソッドをアルファベット順に書きましょう。1行より長いタグメソッドは別のファンクションとしてスクリプトを書いておいて、リンクさせましょう。

### Why?

* タグプロパティとメソッドをスクリプトの最初に書くことで、マークアップにタグのどの部分が使えるのかすぐ判断するため。
* プロパティとメソッドをアルファベット順に並べることで探しやすくするため。
* それぞれのタグメソッドとプロパティの宣言を1行にすることでひと目でタグ全体を把握できるから。
* 関数全体はタグメソッドよりあとに記述することで、実装の詳細を隠すため。

### How?

タグプロパティとメソッドをトップに書く。

```javascript
/* recommended: メソッドより先にアルファベット順にプロパティを書く */
var tag = this;
tag.text = '';
tag.todos = [];
tag.add = add;
tag.edit = edit;
tag.toggle = toggle;

function add(event) {
    /* ... */
}

function edit(event) {
    /* ... */
}

function toggle(event) {
    /* ... */
}

/* avoid: don't spread out tag properties and methods over script */
/*  avoid: スクリプト全体にタグやメソッドを書くのはやめる*/
var tag = this;

tag.todos = [];
tag.add = function(event) {
    /* ... */
}

tag.text = '';
tag.edit = function(event) {
    /* ... */
}

tag.toggle = function(event) {
    /* ... */
}
```

mixinやobservableも最初に記述しましょう。

```javascript
/* recommended */
var tag = this;
// alphabetized properties
// alphabetized methods
tag.mixin('someBehaviour');
tag.on('mount', onMount);
tag.on('update', onUpdate);
// etc
```

[↑ 目次に戻る](#目次)

## ES6風シンタックスを避ける

Riotは[ *ES6風* ショートハンドシンタックス](http://riotjs.com/guide/#tag-syntax)をサポートしています。Riotは ES6風ショートハンドシンタックスの`methodName() { }`を`this.methodName = function() {}.bind(this)`にコンパイルします。これは標準的ではないので、この ES6風ショートハンドシンタックスは使うべきではありません。

### Why?

* Riotjsの提供するES6風ショートハンドシンタックスは標準的ではないので開発者を混乱させる可能性があるから。
* タグのスクリプトは本当のES6 クラスではないのでIDEが ES6風クラスメソッドシンタックスを解釈できないから。
* どのメソッドがタグに紐付けられているか明確にしておくべきなので、マークアップでも使えるようにするべきである。ショートハンドシンタックスはコーディングの原則である透明性や理解しやすさを曖昧にするから。

### How?

 `methodName() { }`シンタックスではなく`tag.methodName =`を使いましょう。

```javascript
/* recommended */
var tag = this;
tag.todos = [];
tag.add = add;

function add() {
    if (tag.text) {
        tag.todos.push({ title: tag.text });
        tag.text = tag.input.value = '';
    }
}

/* avoid */
todos = [];

add() {
    if (this.text) {
        this.todos.push({ title: this.text });
        this.text = this.input.value = '';
    }
}
```

**ヒント** : ES6風シンタックスはpre-compilationのときに`type`を`none`にセットすることで解除できます。[Disable transformation of the fake ES6 syntax](http://riotjs.com/guide/compiler/#no-transformation)

```bash
riot --type none
```

[↑ 目次に戻る](#目次)


## `tag.parent`は避ける

Riotは [nested tags](http://riotjs.com/guide/#nested-tags) を使うことで、`tag.parent` を通じて親コンテキストにアクセスできます。しかし、タグモジュール外からコンテキストにアクセスすることは[FIRST](https://addyosmani.com/first/) の[モジュールベースの開発](#モジュールベースの開発)に背きます。そのため、 **`tag.parent`の利用は避けるべきです** 。

The exception to this rule are anonymous child tags in a [for each loop](http://riotjs.com/guide/#loops) as they are defined directly inside the tag module.

[for each loop](http://riotjs.com/guide/#loops)内の匿名の子タグは、タグモジュール内に直接定義されているため例外です。

### Why?

* 親にアクセスすることで、子タグが親のプロパティを変更できるようになると、予期せぬ動作を引き起こすから。
* タグモジュールは他のモジュールと同じように独立して動くべき。もしタグが親にアクセスすると、このルールが壊れるため。
* もしタグが親にアクセスする必要がある場合、他のコンテキストで再利用することができなくなるため。
* 親にアクセスすることで子タグは親のプロパティを変更できる。これは、予期せぬ動きを引き起こす可能性があるため。

### How?

* テンプレート変数を使って親から子に値を渡す。
* テンプレート変数のコールバックを使って親タグに定義したメソッドを子タグに渡す。

```html
<!-- recommended -->
<parent-tag>
	<child-tag value="{ value }" /> <!-- pass parent value to child -->
</parent-tag>

<child-tag>
	<span>{ opts.value }</span> <!-- use value passed by parent -->
</child-tag>

<!-- avoid -->
<parent-tag>
	<child-tag />
</parent-tag>

<child-tag>
	<span>value: { parent.value }</span> <!-- don't do this -->
</child-tag>
```
```html
<!-- recommended -->
<parent-tag>
	<child-tag on-event="{ methodToCallOnEvent }" /> <!-- use method as callback -->
	<script>this.methodToCallOnEvent = () => { /*...*/ };</script>
<parent-tag>

<child-tag>
	<button onclick="{ opts.onEvent }"></button> <!-- call method passed by parent -->
</child-tag>

<!-- avoid -->
<parent-tag>
	<child-tag />
	<script>this.methodToCallOnEvent = () => { /*...*/ };</script>
<parent-tag>

<child-tag>
	<button onclick="{ parent.methodToCallOnEvent }"></button> <!-- don't do this -->
</child-tag>
```
```html
<!-- allowed exception -->
<parent-tag>
	<button each="{ item in items }"
		onclick="{ parent.onEvent }"> <!-- okay, because button is not a riot tag -->
		{ item.text }
	</button>
	<script>this.onEvent = (e) => { alert(e.item.text); }</script>
</parent-tag>
```

[↑ 目次に戻る](#目次)


##  `each ... in`シンタックスを使う

Riotでは様々なloop表記が使えます。配列の要素(`each="{ item in items }"`)、オブジェクトのキーと値(`each="{ key, value in items }"`) 、そしてショートハンド (`each="{ items }"`)表記です。このショートハンドは混乱を招くでしょう。そのため **`each ... in` シンタックスを使うべきです**。

### Why?

Riotは新しいタグインスタンスを`each`のループを使って作成します。
ショートハンド表記を使っていると、現在のitemのメソッドやプロパティは現在のタグインスタンス (ローカルの `this`) に紐付けられます。そのためマークアップを見ても中身が明らかではなく混乱のもととなります。そのため**`each ... in` シンタックスを使うべきです**。

### How?

`each="{ items }"` シンタックスの代わりに、 `each="{ item in items }"` か `each="{ key, value in items }"`  を使いましょう。

```html
<!-- recommended: -->
<ul>
    <li each="{ item in items }">
      	<label class="{ completed: item.done }">
			<input type="checkbox" checked="{ item.done }"> { item.title }
      	</label>
    </li>
</ul>

<!-- recommended: -->
<ul>
    <li each="{ key, item in items }">
      	<label class="{ completed: item.done }">
			<input type="checkbox" checked="{ item.done }"> { key }. { item.title }
      	</label>
    </li>
</ul>

<!-- avoid: -->
<ul>
    <li each="{ items }">
      	<label class="{ completed: done }">
			<input type="checkbox" checked="{ done }"> { title }
      	</label>
    </li>
</ul>
```

[↑ 目次に戻る](#目次)


## スタイルは外部ファイルに置く


開発者の都合上、Riotはタグ要素のスタイルを[ネストされた`<style>` タグ](http://riotjs.com/guide/#tag-styling)の中で定義してもよいことになっています。これらのスタイルはタグ要素に[scope](http://riotjs.com/guide/#scoped-css)されるので、Riotではカプセル化できません。その代わりにRiotはタグからスタイルを抽出してruntime上でドキュメントに注入しています。Riotはカプセル化の機能がないのでネストされたスタイルをJavaScriptにコンパイルします。 **スタイルは外部ファイルにおくべきです。**


### Why?

* 外部スタイルシートはブラウザーでハンドルされ、Riotやタグファイルからは独立する。こうすることによって、JavaScriptでエラーが起こってロードされない場合もスタイルが適用されるから。
* 外部スタイルシートではpre-processor(Less、Sass、PostCSSなど)を利用でき、すでに使っているビルドツールを使うこともできるから。
* 外部スタイルシートならminifyでき、保存とキャッシュを別にすることができ、パフォーマンスを向上させることができるため。
* Riot表記はネストされた`<style>`では利用できないのでメリットがないから。


### How?

タグとマークアップに紐づくスタイルは別のスタイルシートファイルに切り出し、モジュールディレクトリ内のタグファイルのとなりに配置する。

```
my-example/
├── my-example.tag.html
├── my-example.(css|less|scss)    <-- external stylesheet next to tag file
└── ...
```

[↑ 目次に戻る](#目次)


## タグ名をスタイルスコープとして使う

Riotタグ要素はカスタムエレメントで、スタイルスコープのルートとしてもよく使われています。対照的に、モジュール名はCSSのクラス名として使えます。

### Why?

* タグ要素でスタイルをスコープすることで、予測しやすくなり、スタイルがタグ要素の外に流出することを防ぐから。
* moduleディレクトリと同じ名前を使うことでRiotタグとスタイルルートが一緒に使われていることが理解しやすくなるから。

### How?

タグ名をセレクタ、親セレクタ、プレフィックスとして使う。(CSS命名規則に合わせる)

```css
/* recommended */
my-example { }
my-example li { }
.my-example__item { }

/* avoid */
.my-alternative { } /* not scoped to tag or module name */
.my-parent .my-example { } /* .my-parent is outside scope, so should not be used in this file */
```


注意: もしRiotタグに[`data-is=`](http://riotjs.com/guide/#html-elements-as-tags) (introduced in [v2.3.17](http://riotjs.com/release-notes/#march-9-2016))を使っている場合は、 `.my-example` の代わりに `[data-is="my-example"]` をCSSセレクターとして使えます。

[↑ 目次に戻る](#目次)


## 自分のタグAPIをドキュメント化する

Riotタグのインスタンスはアプリケーション内部のタグ要素を使って作られています。このインスタンスはカスタム属性を通して設定されています。他の開発者がタグを利用するときのために、これらのカスタム属性 (つまり、タグのAPI)を`README.md` に記載しておきましょう。

### Why?

* ドキュメント化することで、コードを見なくてもモジュールについてのハイレベルな理解ができるから。モジュールにアクセスしやすく、使いやすくなる。
* タグのAPIは設定されたカスタム属性のあつまりであって、タグを開発しない利用者にとって一番興味がある部分だから。
* ドキュメント化することによってAPIを正式なものにし、タグを変更するときにどの機能に互換性をもたせるべきか他の開発者に知らせることができるから。
* `README.md`は最初に読むべきドキュメントのファイル名のデファクトスタンダードで、Github, Bitbucket, Gitlabなどのコードホスティングサービスではソースのディレクトリを開くとデフォルトで `README.md`を表示し、この構成はmoduleディレクトリでも同じだから。


### How?

タグのモジュールディレクトリに `README.md`を追加する。

```
range-slider/
├── range-slider.tag.html
├── range-slider.less
└── README.md
```

READMEファイルの中でmoduleの機能と使い方を説明します。
タグモジュールの場合はAPIであるカスタム属性について説明すると便利です。

```markdown
# Range slider

## Functionality

The range slider lets the user to set a numeric range by dragging a handle on a slider rail for both the start and end value.

This module uses the [noUiSlider](http://refreshless.com/nouislider/) for cross browser and touch support.

## Usage

`<range-slider>` supports the following custom tag attributes:

| attribute | type | description |
| --- | --- | --- |
| `min` | Number | number where range starts (lower limit).|
| `max` | Number | Number where range ends (upper limit).|
| `values` | Number[] *optional* | Array containing start and end value.  E.g. `values="[10, 20]"`. Defaults to `[opts.min, opts.max]`.|
| `step` | Number *optional* | Number to increment / decrement values by. Defaults to 1.|
| `on-slide` | Function *optional* | Function called with `(values, HANDLE)` while a user drags the start (`HANDLE == 0`) or end (`HANDLE == 1`) handle. E.g. `on-slide={ updateInputs }`, with `tag.updateInputs = (values, HANDLE) => { const value = values[HANDLE]; }`.|
| `on-end` | Function *optional* | Function called with `(values, HANDLE)` when user stops dragging a handle.|

For customising the slider appearance see the [Styling section in the noUiSlider docs](http://refreshless.com/nouislider/more/#section-styling).
```

[↑ 目次に戻る](#目次)


## タグのデモを追加する

それぞれ違うコンフィグで表示させたデモを `*.demo.html` ファイルとして追加することで、タグがどのように使われるかを示します。

### Why?

* タグのデモでモジュールがそれ単体で動くことを証明するため。
* タグのデモは開発者がドキュメントやコードを読み込む前のプレビューになるから。
* デモをすることでタグを使う可能性のあるコンフィグやバリエーションに気づくため。

### How?

モジュールディレクトリに `*.demo.html`ファイルを追加する。

```
city-map/
├── city-map.tag.html
├── city-map.demo.html
├── city-map.css
└── ...
```

デモファイルの中身:

* runtime内でもコンパイルするために、 `riot+compiler.min.js` をインクルードする
* タグファイル(e.g. `./city-map.tag.html`)をインクルード
* `demo` タグ(`<yield/>`)を作り、デモ内に埋め込む（そうしないとオプション属性が効かないので）
* `<demo>` タグの中にデモの中身を書く
* おまけに `<demo>` タグに`aria-label`を追加し、タイトルバーとして使う
* `riot.mount('demo', {})`を使ってイニシャライズする

 `city-tag`モジュール内のデモ例:

```html
<!-- modules/city-map/city-map.demo.html: -->
<body>
    <h1>city-map demos</h1>

    <demo aria-label="City map of London">
        <city-map location="London" />
    </demo>

    <demo aria-label="City map of Paris">
        <city-map location="Paris" />
    </demo>

    <link rel="stylesheet" href="./city-map.css">

    <script src="path/to/riot+compiler.min.js"></script>
    <script type="riot/tag" src="./city-map.tag.html"></script>
    <script>
        riot.tag('demo','<yield/>');
        riot.mount('demo', {});
    </script>

    <style>
    	/* add a grey bar with the `aria-label` as demo title */
    	demo:before {
        	content: "Demo: " attr(aria-label);
	        display: block;
        	background: #F3F5F5;
        	padding: .5em;
        	clear: both;
        }
    </style>
</body>
```


注意: ビルドスクリプトを使うともっときれいになります。

[↑ 目次に戻る](#目次)


## タグファイルをlintする

Linterはコードの一貫性を保ち、シンタックスエラーをトレースする補助をしてくれます。いくつか追加の設定をすればRiotタグファイルもlintできます。

### Why?

* タグファイルをリントすることですべての開発者がおなじコードスタイルになるから。
* tagファイルをリントすることで手遅れになる前にシンタックスエラーに気づけるから。

### How?

Linterが `*.tag.html` ファイルのスクリプトを抽出するようにします。[スクリプトは`<script>` タグの中に書き込み](#use-script-inside-tag)、[タグ表現をシンプルにします](#keep-tag-expressions-simple)（そうじゃないとLinterがわかってくれません）。Linterでグローバル変数の `riot` とタグの`opts` を設定しましょう。

#### ESLint

ESLintでタグファイルからスクリプトを抽出するには[ESLint HTML plugin](https://github.com/BenoitZugmeyer/eslint-plugin-html#eslint-plugin-html)が必要です。
 `modules/.eslintrc`でESLintを設定しましょう（IDEも解釈できるように）。


```json
{
	"extends": "eslint:recommended",
	"plugins": ["html"],
	"env": {
		"browser": true
	},
	"globals": {
		"opts": true,
		"riot": true
	}
}
```

Run ESLint
ESLintを実行します。

```bash
eslint modules/**/*.tag.html
```

#### JSHint

[JSHint](http://jshint.com/) はHTMLをパースし (`--extra-ext` を使います) 、スクリプトを抽出します(`--extract=auto` を使います)。

 `modules/.jshintrc`でJSHintを設定しましょう（IDEも解釈できるように）。

```json
{
	"browser": true,
	"predef": ["opts", "riot"]
}
```

Run JSHint
JSHintを実行します。

```bash
jshint --config modules/.jshintrc --extra-ext=html --extract=auto modules/
```

Note: JSHint does not accept `tag.html` as extension, but only `html`.
ヒント: JSHintは`html`のみを拡張子として認識し、`tag.html`拡張子は認識しません。

[↑ 目次に戻る](#目次)


## プロジェクトにバッジをつける

このガイドへのリンクは *RiotJS Style Guide badge* を使ってください。

[![RiotJS Style Guide badge](https://cdn.rawgit.com/voorhoede/riotjs-style-guide/master/riotjs-style-guide.svg)](https://github.com/voorhoede/riotjs-style-guide)

### Why?

他の開発者に自分のプロジェクトがRiotjsスタイルガイドに従っていることを示すため。このガイドがどこにあるか教えるため。

### How?

プロジェクトにバッジを貼り付けてください。マークダウンだとこう。

```markdown
[![RiotJS Style Guide badge](https://cdn.rawgit.com/voorhoede/riotjs-style-guide/master/riotjs-style-guide.svg)](https://github.com/voorhoede/riotjs-style-guide)
```

htmlだとこう。

```html
<a href="https://github.com/voorhoede/riotjs-style-guide">
    <img alt="RiotJS Style Guide badge"
    	 src="https://cdn.rawgit.com/voorhoede/riotjs-style-guide/master/riotjs-style-guide.svg">
</a>
```

[↑ 目次に戻る](#目次)