守ってますか?コードの記述ルール。世界標準のルールとその使い方まとめ

Pocket

守ってますか?コードの記述ルール
photo credit: Riebart via photopin cc

Web制作でよくある仕事の1つに既存サイトのリニューアルや一部修正依頼などがあります。修正作業をしていて困るのはコードの記述方法に一貫性がないことです。

全ての人に同じルールでやってほしいということではありません。少なくとも同じプロジェクト内ではコーディングに一貫性がないと非常に読みづらく、難解なコードが出来上がってしまいます。そうならないためにも、コーディングの記述ルールについてはもう一度確認しておきたいところです。

どんなルールがあるのかは、最近Githubで見つけたものを参考に見ていきたいと思います。

世界標準のコーディング記述ルール

HTMLのコーディングルール

HTMLのルールはこちら。英語しかないので簡単に翻訳しながら見てみます。

一般原則
1つのプロジェクトに多くの人が参加していても、一人で書いたように記述ルールを合わせること。自分の書きやすい方法もあると思いますが、多人数でやる場合は必ず揃えましょう。

HTMLのホワイトスペース
次に余白について。余白はスペースかタブかどちらかを使うこと。同じプロジェクトに混在してはいけません。スペースを使用する場合は4スペースが推奨されています。

フォーマット
フォーマットについては以下のようにリストアップされています。

  • 属性内のテキストは小文字
  • 1行で1要素
  • ネストされた要素にはそれぞれ1レベルのインデントを入れる
  • link,script,style要素にtype属性を入れない
  • 閉じタグは忘れずに入れる
  • brやhrなどセルフクロージング要素にスラッシュ入れない

//書き方の例
<div class="tweet">
    <a href="path/to/somewhere">
        <img src="path/to/image.png" alt="">
    </a>
    <p></p>
    <button disabled>Reply</button>
</div>

書き方の例外として、属性が複数ある場合は以下のような書き方もOK。

//書き方の例2
<a class="[value]"
 data-action="[value]"
 data-id="[value]"
 href="[url]">
    <span>[text][/text]</span>
</a>

HTMLのclassネーミング
id名やクラス名のつけ方は難しいことですが、重要なこと。機械的な名前をつけると、そのときは良くても後から見てこれ何?っていうことになる可能性大。

難しくする必要はなく、パッと見てそれが何か分かるようにすると良いと思います。例えばアイコンなら先頭にicon_をつけて後ろに配置場所を書くなどです。icon_side_title

//悪い例
<div class="cb s-scr"></div>


//良い例
<div class="column-body is-scrollable"></div>

CSSのコーディングルール

次はCSSルール。Githubのこちらに日本語化されたものがあります。ここでは特に重要なところだけ確認していきます。

CSSコメントのつけ方
忘れがち&メンドクサイことですが、コメントは必ず入れるようにしましょう。他の人が見てすぐにわかるように、なぜこのスタイルが必要なのかなども入れておきます。以下はコメントのフォーマット。

//CSSのコメントフォーマット

/* ==============================================================
   セクションコメントブロック
   ============================================================= */

/* サブ・セクションコメントブロック
   =============================================================== */

/*
 * グループコメントブロック
 * 複数行になるドキュメントや説明の際に最適
 */

/* 基本コメント */


//SCSSのコメントフォーマット

// =============================================================
// セクションコメントブロック
// =============================================================

// サブ・セクションコメントブロック
// =============================================================

//
// グループコメントブロック
// 複数行になるドキュメントや説明の際に最適
//

// 基本コメント

CSSのフォーマットと宣言順
CSSのフォーマットも揃えておくと見やすくなります。大事なのは以下の部分。

  • 複数セレクタがある場合、セレクタは1行ずつ記述
  • CSSは1行ずつ記述し、それぞれインデントをつける
  • 宣言順は特定のルールに沿って決めること

宣言順を決めるのに悩んだらSublimeTextのCSScombをオススメします。これならショートカットキー一発で自動的にそろえてくれます。使い方はSublimeTextを使いこなす10のテクニック

javascriptのコーディングルール

さいごにjavascriptの記述ルール。こちらに日本語テキストがあります。非常に長いので重要なところだけ紹介します。

javascriptのスペース、改行、インデントの書き方
HTMLやCSSでもあったように、ホワイトスペースをスペースでやるかタブでやるかは自由です。大事なのは一貫性。中には1行で全て書く人もいますが、それが見づらくなっては意味がないのでできるだけ改行して、インデントもつけます。

// あまりに読みにくい構文の例

if(condition) doSomething();

while(condition) iterating++;

for(var i=0;i<100;i++) someIterativeFn();


// 可読性を促進するためにスペースを使います

if ( condition ) {
  // 文
}

while ( condition ) {
  // 文
}

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

// より良い例:

var i,
  length = 100;

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


//もしくはこんな感じで

if (condition) {
  // 文
}

while (condition) {
  // 文
}

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

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

クオート、行末と空行
シングルクオートにするか、ダブルクオートにするかはどちらでもOK。行末などに意味のないスペースを入れることはやめましょう。

javascriptのネーミング
CSSと同じくjavascriptのネーミングも分かりやすさを重視します。

// 悪い名前を使ったコードの例

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



// 改善したネーミングを使ったコードの例

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 ] );
}

さいごに

githubのほうにも書いてありますが、必ずしもここにある書き方を押し付ける必要はありません。制作会社ごとに少しずつ違っても良いのですが、重要なのは一貫性です。同じファイル内で一貫性がないコードは非常に読みづらいです。

とくに独学でやってきた方はこの記述ルールを参考にしながら自分の書き方を見直してみて下さい。ここまで読んでいただきありがとうございました。

おまけ

記述ルールが大事と言っても現実には読みづらいコードが溢れています。そんなコードに出会ったときに少しでも楽するために以下のツールをオススメします。

HTML整形ツール
一貫性のないインデントや見づらい改行などを整形してくれる、ありがたいツール。このサイトのヘッダーにあるリンクからCSS、javascript、SQL、PHPの整形ツールへ移動できます。ありがたいですね。