社内でコーディング規約を作ろう

Web Create
2016.09.15

これまでの数年、トライムでは古株メンバーが主だったために、コーディングについて細かい取り決めをしなくても、大まかなルールの共有ができていました。しかし最近、大幅な増員を目指し求人を出しており、少しずつですが新しいメンバーが増えてきました。

そんな状況で全員が自由にコーディングしてしまうと、他の人が引き継いだり、修正したりする際に困る場合があります。そこで社内でコーディング規約を作りました。ルールは主にGoogleのガイドライン（Google HTML/CSS Style Guide）を元にしています。

またベースになるファイルを作り、GitHubに登録しました。
ベースファイルにはよく使うJSや、mixinなども入れてあり、さらにWikiでそれぞれの使い方を解説しています。GitHubはこういう使い方もできるので便利ですね。

https://github.com/trymcom/html

新たなサイトをコーディングする時には、各自ここからダウンロードして作業を始めます。
コーディング規約も大切ですが、こういう基礎を作っておくだけでも、ある程度みんなのコーディングを共通化することができます。

さて、以下にトライムのコーディング規約をご紹介します。

全般的なスタイルルール

プロトコル

埋め込みリソースからプロトコル表記（http:,https:）を省略する。

<!-- NG -->
<script src="http://www.google.com/js/gweb/analytics/autotrack.js"></script>

<!-- OK -->
<script src="//www.google.com/js/gweb/analytics/autotrack.js"></script>

一般的な書式ルール

インデント

半角スペース2つ分でインデントする。
タブを使ったり、タブとスペースを混在させるのはNG。

<ul>
  <li>Fantastic</li>
  <li>Great</li>
</ul>

余分な空白行を増やさない

空白行を入れる場合基本的に1行にする。

<!-- NG -->
<div class="block">

  <div class="item">
    <p>Text</p>
  </div>



  <div class="item">
    <p>Text</p>
  </div>

</div>

<!-- OK -->
<div class="block">

  <div class="item">
    <p>Text</p>
  </div>

  <div class="item">
    <p>Text</p>
  </div>

</div>

コメントを入れる

ブロックごとにコメントを入れる。
同じ要素が繰り返し続く場合もコメントを入れる。

<!-- header -->
<header>

</header>
<!-- /header -->

<!--contents-->
<div id="contents">

  <!-- article -->
  <article>

  </article>
  <!-- /article -->

  <!-- article -->
  <article>

  </article>
  <!-- /article -->

</div>
<!--/contents-->

<!-- footer -->
<footer>

</footer>
<!-- /footer -->

IDは最低限に

IDは他のスタイルで上書きが必要な場合に優先度が高く、!importantの原因となります。
レイアウトに関わる部分やJSで利用する場合を除き、IDの付与は控えめにしましょう。

<h2 id="title" class="works">タイトル</h2>

#title {
  font-size: 2em;
  border-bottom: 1px solid #000;
}

.works {
  border-bottom-color: #f00; /* #titeが優先され、上書きできない */ 
}

クラスを増やしすぎない

CSSの子孫セレクタや::hth-childを利用し、不要なクラスを増やさない。

<!-- NG -->
<header>
  <h1 class="logo"><img src="#"></h1>
</header>

<!-- NG -->
<div id="elem">
  <p class="text">Text</p>
  <p class="text">Text</p>
  <p class="text">Text</p>
</div>

<!-- OK -->
<header>
  <h1><img src="#"></h1>
</header>

<!-- OK -->
<div id="elem">
  <p>Text</p>
  <p>Text</p>
  <p>Text</p>
</div>

大文字/小文字

小文字のみ使用する。alt属性など値が文字列の場合は除く。

<!-- NG -->
<A HREF="/">Home</A>

<!-- OK -->
<img src="google.png" alt="Google">

文末のスペース

文末のスペースを削除する。

<!-- NG -->
<p>What?_</p> 

<!-- OK -->
<p>Yes please.</p>

HTMLのスタイルルール

HTMLのバリデート

可能な限り適切なHTMLを記述すること。
そうでないとパフォーマンスが低下するような場合でない限りは、ちゃんと書く。
「W3C HTML validator」などの検証ツールを使用する。

<!-- NG -->
<title>Test</title>
<article>This is only a test.

<!-- OK -->
<!DOCTYPE html>
<meta charset="utf-8">
<title>Test</title>
<article>This is only a test.</article>

セマンティックに書く

目的に応じてHTMLを記述する。
見出しならhx要素、段落ならp要素、アンカーならa要素など目的に応じたHTML要素を使う（「HTMLタグ」という言い方は間違い）。
リンクならa要素で書く。onclickのようなJavaScriptな振る舞いのものを要素の属性に入れない。

<!-- NG -->
<div onclick="goToRecommendations();">All recommendations</div>

<!-- OK -->
<a href="recommendations/">All recommendations</a>

マルチメディアの代替コンテンツ

マルチメディアの要素には、代替コンテンツを提供する。
画像には、意味のある代替テキストをalt属性として、動画・オーディオコンテンツにはキャプションを記述する。
装飾的な用途の場合など意味を持たない画像については、代替テキストは記述せずにalt=””とする。

<!-- NG -->
<img src="spreadsheet.png">

<!-- OK -->
<img src="spreadsheet.png" alt="Spreadsheet screenshot.">

実体参照

不要な実体参照は使用しないこと。
UTF-8においては、—（—）・”（”）・☺（☺）のような文字は実体参照を使う必要はない。
HTMLで特別な意味を持つ文字（ < や & など）は例外。

<!-- NG -->
The currency symbol for the Euro is &ldquo;&eur;&rdquo;.

<!-- OK -->
The currency symbol for the Euro is “€”.

type属性

CSSとJavaScriptのtype属性は省略する。
HTML5ではデフォルトの言語として解釈されるため。

<!-- NG -->
<link rel="stylesheet" href="//www.google.com/css/maia.css" type="text/css">

<!-- OK -->
<link rel="stylesheet" href="//www.google.com/css/maia.css">


<script src="//www.google.com/js/gweb/analytics/autotrack.js" type="text/javascript"></script>

<!-- OK -->
<script src="//www.google.com/js/gweb/analytics/autotrack.js"></script>

HTMLの書式ルール

全般的な書式

ブロック要素・リスト要素・テーブル要素は改行してから記述し、それらの子要素にはインデントを入れる。

<blockquote>
  <p><em>Space</em>, the final frontier.</p>
</blockquote>

<ul>
  <li>Moe</li>
  <li>Larry</li>
  <li>Curly</li>
</ul>

<table>
  <thead>
    <tr>
      <th scope="col">Income</th>
      <th scope="col">Taxes</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>$ 5.00</td>
      <td>$ 4.50</td>
    </tr>
  </tbody>
</table>

CSSのバリデート

可能な限り適切なCSSを記述すること。
CSSバリデーターにバグがある場合や独自の構文を必要としない限りは、ちゃんと書く。
HTML同様W3C CSS validatorなどのツールで検証する。

IDとクラスの命名

IDとクラス名にはちゃんと意味の分かる名前を使うこと。
見た目を反映したものやそれが何を表しているか不可解な名前ではなく、要素の目的や役割を反映した名前を付ける。

/* NG: 意味が分からない */
#yee-1901 {}

/* NG: 見た目を表してる */
.button-green {}
.clear {}

/* OK: 役割を表してる */
#gallery {}
#login {}
.video {}

/* OK: 汎用的な名前 */
.aux {}
.alt {}

IDとクラスの命名スタイル

意味の分かる範囲でできるだけ短いIDとクラス名を使う。
短くしすぎて意味がわからなくなるようなのはNG。

/* NG */
#navigation {}
.atr {}

/* OK */
#nav {}
.author {}

タイプセレクタの記述

IDとクラス名にタイプセレクタは記述しない。
パフォーマンスを考慮して不要な子孫セレクタも避ける。

/* NG */
ul#example {}
div.error {}

/* OK */
#example {}
.error {}

ショートハンドプロパティ

可能な限りショートハンドでプロパティを書く。

/* NG */
border-top-style: none;
font-family: palatino, georgia, serif;
font-size: 100%;
line-height: 1.6;
padding-bottom: 2em;
padding-left: 1em;
padding-right: 1em;
padding-top: 0;

/* OK */
border-top: 0;
font: 100%/1.6 palatino, georgia, serif;
padding: 0 1em 2em;

「0」と単位

値が「0」なら単位を省略する。

margin: 0;
padding: 0;

小数点の頭の「0」

小数点の頭の「0」は省略する。

font-size: .8em;

フォントサイズの単位

フォントサイズはremで指定。
テキスト間のmargin、paddingの単位はemまたはremを指定。

margin-bottom; 1em;
padding-bottom; 1em;
font-size: 1.4rem;

URI値の引用符

url()での指定において、””（ダブルコーテーション）や”（シングルコーテーション）などのURI値の引用符を省略すること。

@import url(//www.google.com/css/go.css);

HEX形式のカラーコード

HEX形式のカラーコードで3文字で表記できるものは3文字にする。

/* NG */
color: #eebbcc;

/* OK */
color: #ebc;

IDやクラス名の区切り文字

IDやクラス名の別々の単語はキャメルケースで繋ぐ。

/* NG: [demo]と[image]が繋がってる */
.demoimage {}

/* NG: アンダーバーで繋がってる */
.error_status {}

/* NG: ハイフンで繋がってる */
.error-status {}

/* OK */
#videoID {}
.adsSample {}

CSSハック

ユーザーエージェント別の対応のためにCSSハックを使う前に別の方法を試してみること。
CSSハックは、ユーザーエージェントごとの違いを吸収するためには簡単で魅力的な方法だけど、プロジェクト全体のコードの品質を落とすことにもなるので「最後の手段」として考えること。

CSS書式ルール

プロパティの記述順序

Atomではcsscombでソート可能。
インストール後、プラグインの設定画面からConfigure presetをrecommendに設定。
具体的な順序は下記を参照。

https://github.com/1000ch/atom-csscomb/blob/v2.0.4/recommend.json

ブロック単位のインデント

その階層がわかるようにブロック単位でコードをインデントする。

@media screen, projection {
  html {
    background: #fff;
    color: #444;
  }
}

クラスのネストは最小限にする

ネストが深くなると、レスポンシブでスタイルの上書きが上手くいかず、
!importantの多様に繋がります。
やむを得ない場合を除きネストは控えめにしましょう。

//NG
#wrap {
  #wrapInner {
    #page {
      #contents {
        #contentsInner {
          #main {
            section {
              margin-bottom: 50px;
              .item {
                .image {
                  float: left;
                }
                .text {
                  float: right;
                }
              }
            }
          }
        }
      }
    }
  }
}

//OK
section {
  margin-bottom: 50px;
  .item {
    .image {
      float: left;
    }
    .text {
      float: right;
    }
  }
}

ネストの深さは何回層までという決まりはありません。
汎用的に使うクラスなら、浅いほうが良いですが、
他のスタイルとバッティングしないように注意が必要です。

プロパティの終端

すべてのプロパティの終端はセミコロンを書くこと。

/* NG */
.test {
  display: block;
  height: 100px
}

/* OK */
.test {
  display: block;
  height: 100px;
}

プロパティ名の終端

すべてのプロパティ名の終端にはコロンの後にスペースを入れること。

/* NG */
h3 {
  font-weight:bold;
}

/* OK */
h3 {
  font-weight: bold;
}

セレクタとプロパティの分離

別々のセレクタとプロパティは改行して書くこと。

/* NG */
a:focus, a:active {
  position: relative; top: 1px;
}

/* OK */
h1,
h2,
h3 {
  font-weight: normal;
  line-height: 1.2;
}

CSSルールの分離

別々のCSSルールは改行して一行間を空けて書く。

html {
  background: #fff;
}

body {
  margin: auto;
  width: 50%;
}

CSSメタルール

セクションのコメント

セクションごとにコメント（任意）を記述する。

/* =========================================================
 Level 1
========================================================= */
#adw-header {}

/* Level 2
--------------------------------------------------------- */
.adw-gallery {}

/* ----- Lavel 3 ----- */
section {}

jQueryプラグインの読み込みルール

一つのファイルにまとめる。

複数のプラグインファイルを読み込むときは、
plugins.jsやplugins.cssにまとめて読み込む。ライセンス表記は消さない。
scssを利用しているなら下記のようにインクルードする。

/* =========================================================
  Remodal
========================================================= */
@import "_remodal.scss";
@import "_remodal-default-theme.scss";

/* =========================================================
  Horizon Swiper
========================================================= */
@import "_horizon-swiper.min.scss";

/* =========================================================
  Flickity
========================================================= */
@import "_flickity.scss";

/* =========================================================
  Drawer
========================================================= */
@import "_jquery.mmenu.all.scss";

最後に

「一貫性を持ちましょう。」

コードを編集する前に、あなたは周りのコードを見て、そのスタイルに沿って書きましょう。算術演算子の前後にスペースがあるなら、あなたもそうすべきです。コメントの周りが#で囲まれているなら、そうすべきです。

スタイルガイドラインを持つことのポイントは、コーディングの共通の語彙を持つことです。ここでは、グローバルなスタイルルールを提示していますが、ローカルなルールも重要です。もしあなたが追加したコードのスタイルが、周りの既存のコードと大幅に異なっていると、他人がそのコードを触るとき、リズムが崩れてしまいます。このようなことは避けましょう。

まとめ

長くなりましたが、以上がトライム社内のコーディング規約です。
それほど厳密に遵守してもらっているわけではありませんが、一度目を通してからコーディングしてもらうと、それだけで全然違います。

コーダーそれぞれの自由なコーディングに困った経験がありましたら、ぜひ参考にコーディング規約を作ってみてください。

【WordPress】複雑なループでもシンプルに書こう 〜IF文 地獄にならないために〜

【Movable Type】編集画面でタイトルの文字数カウント

【Movable Type】IF文不要！カテゴリ毎にレイアウトを変える

【MovableType】大量にカスタムフィールドがあるテンプレートをスマートにする書き方

【重要！】WordPress 4.7.1に深刻な脆弱性 コンテンツが改ざんされるとこうなる

韓国モール型ECサイト「29CM」コンテンツ内のクレジットの見せ方

韓国モール型ECサイト「SEOUL STORE.」のUI/UX（後編）

韓国モール型ECサイト「SEOUL STORE.」のUI/UX（前編）

韓国最大規模 モール型ECサイト「MUSINSA」のUI/UX（後編）

韓国最大規模 モール型ECサイト「MUSINSA」のUI/UX（前編）

リテールメディアとは？Web制作会社が提案する新たな広告戦略

GA無料診断キャンペーン実施のお知らせ

マーケティングオートメーションの基礎知識 Vol.02

マーケティングオートメーションの基礎知識 Vol.01

Webマーケティングの基礎知識

新型肺炎の影響による在庫状況に関して

【ご挨拶】ノベルティ本舗

Webブランディングに強みをおいている会社のご紹介

Webマーケティングに強みをおいている会社のご紹介

Webデザインに強みをおいている会社のご紹介

【報告】4ヶ月でPHP Laravelを学べる学校を開校いたしました！

半期報告会を行いました！

Adobe Fireflyベータ版を使ってみた感想

細かいUIの参考になるアプリ5選

【Shopify】ディスカウントの設定方法

アパレルECサイトでのセール戦略を最大化するためのIT活用法

アパレルECサイトにおけるリターゲティング広告の効果的な活用法

ゼロトラストアーキテクチャ入門：基礎から最新トレンドまでセキュリティ強化のための新常識

デジタルヘルスケアとは？主な要素と最新トレンドを解説

DXとは？IT化やAI活用との違いとメリット・デメリットを徹底解説