Works
Company
社内でコーディング規約を作ろう｜Blog｜株式会社トライム
Keyword
Share
社内でコーディング規約を作ろう
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 “&eur;”. <!-- 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";
最後に
「一貫性を持ちましょう。」
コードを編集する前に、あなたは周りのコードを見て、そのスタイルに沿って書きましょう。算術演算子の前後にスペースがあるなら、あなたもそうすべきです。コメントの周りが#で囲まれているなら、そうすべきです。
スタイルガイドラインを持つことのポイントは、コーディングの共通の語彙を持つことです。ここでは、グローバルなスタイルルールを提示していますが、ローカルなルールも重要です。もしあなたが追加したコードのスタイルが、周りの既存のコードと大幅に異なっていると、他人がそのコードを触るとき、リズムが崩れてしまいます。このようなことは避けましょう。
まとめ
長くなりましたが、以上がトライム社内のコーディング規約です。
それほど厳密に遵守してもらっているわけではありませんが、一度目を通してからコーディングしてもらうと、それだけで全然違います。
コーダーそれぞれの自由なコーディングに困った経験がありましたら、ぜひ参考にコーディング規約を作ってみてください。
Share
Contact
お問い合わせ
トライムは常にお客様へ寄りっ沿った提案をさせていただきます。
自社のEC売上の拡大や人材不足などのお客様のデジタル上の課題を、
様々なアプローチにより解決するお手伝いをいたします！
お気軽にお問い合わせください。
03-6403-3259
受付：10：00 - 19：00
