HTML / CSS コーディング規約例

下記は、HTML と CSS のコーディング規約の例です。

「理想」ではなく、「実業務」に即した規約になるよう考えてみました。

example of html css coding guide


HTML / CSS コーディング規約

  • 文書作成日:2016年01月29日
  • 文書作成者:Webサイトif1tech管理人

この文書では、HTMLとCSSの書式と記述の規則を定義しています。

他のプログラムとの互換性・コード品質・コーダーの互換性向上を目的として指定します。


属性値のURLからスキームを省略する

http:https:の両方のプロトコルで、それぞれのファイルが利用可能でない場合を除き、画像やその他のメディアファイル、スタイルシート、およびスクリプトを指すURLからスキーム部分(http:, https:)を省略する。

URLを相対的に指定するスキームを省略することで、httpプロトコルで取得されるリソースとhttpsプロトコルで取得されるリソースの混在が回避される。

HTMLの非推奨例 <script src="https://www.example.com/js/example.js"></script>
HTMLの推奨例 <script src="//www.example.com/js/example.js"></script>
CSSの非推奨例 .example { background-image: url(https://www.example.com/images/example.png); }
CSSの推奨例 .example { background-image: url(//www.example.com/images/example.png); }

インデントは半角スペース4個

インデントは半角スペース4個とし、タブは使用しない。

コードの難読化回避・可読性向上のために用いる半角スペースは例外とする。

HTMLの推奨例 <ul>
    <li>One</li>
    <li>Two</li>
</ul>
  CSSの推奨例 .example {
    color: blue;
}

半角英数字の小文字を使用する

HTMLの各要素、属性、テキストとCDATAを除く属性値、CSSのセレクタ、プロパティ名、文字列を除くプロパティ値などの記述には半角英数字の小文字を使用する。

HTMLの非推奨例 <IMG CLASS="EXAMPLE" SRC="google.png" ALT="Google" />   CSSの非推奨例 .EXAMPLE {
    color: #E5E5E5;
}
HTMLの推奨例 <img class="example" src="google.png" alt="Google" />   CSSの推奨例 .example {
    color: #e5e5e5;
}

不要な空白文字は削除する

インデント・コードの難読化回避・コードの可読性向上のために用いる以外で、必要性のない空白文字は削除する。

HTMLの非推奨例 ____<div>
________<p>This_<span>is</span>_a_pen.</p>_
____</div>_
HTMLの推奨例 ____<div>
________<p>This_<span>is</span>_a_pen.</p>
____</div>

※ 上記の例は、アンダーバー(_)を空白文字(半角スペース)とした場合。

ファイルのエンコードは、UTF-8(BOMなし)を使用する

HTMLファイルのエンコーディングは、バイトオーダーマークなしのUTF-8を使用する。

HTMLファイルは、ドキュメント内でエンコードを、<meta charset="utf-8" />などと指定する。

HTMLファイルのドキュメント内では、スタイルシートのエンコードを仮定・指定しない。

スタイルシートファイルは、そのドキュメント内でエンコードを適宜指定する。
CSSファイルでUTF-8(BOMなし)であれば、@charset "utf-8";などと指定。

コードの機能を説明するコメントを残す

保守管理しやすいように、必要に応じてコードの機能をコメントする。

CSSは、可読性を向上させるため、セクションごとに見出しを作る。

HTMLの例 <!-- Google Analytics Tracking Code -->
<script>
    (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
    (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
    m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
    })(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
    ga('create', 'UA-00000000-0', 'auto');
    ga('send', 'pageview');
</script>
  CSSの例 /* float の回り込みを解除 */
/* .float-l .float-r と併用 */
.clearfix:after {
    content: ".";
    display: block;
    visibility: hidden;
    clear: both;
    width: 0px;
    height: 0px;
    font-size: 0px;
    line-height: 0px;
    overflow: hidden;
}
CSSの見出し例 /* Structure
 * ====================================================================== */
#container {}
.general-row {}
.general-col {}

/* Header
 * ---------------------------------------------------------------------- */
#header {}
#header .site-name,
#header .search-form {}
/* Site Name */
#header .site-name {}
#header .site-name a {}
#header .site-name a:hover {}
/* Search Form */
#header .search-form {}

コメントアウトでのコード無効化は行わない

HTML/CSSでの<!-- -->/* */を使用したコードの無効化は、Web上で可視化できるうえ、ファイルサイズの膨張とコードの難読化に繋がるため、行わない。

コードを無効化する場合は、完全に削除する。

HTMLで、コードの可読性向上のための改行のコメントアウトは例外とする。

CSSの非推奨例 .example {
    margin: 20px auto;
    /*
    max-widht: 80%;
    max-height: 500px;
    */
    font-size: 14px;
}
  CSSの推奨例 .example {
    margin: 20px auto;
    font-size: 14px;
}
改行の無効化     <label><!--
     -->I am confident that novice users of markup can instantly see any code.<!--
     --><input type="radio" name="radio1" value="0" /><!--
 --></label>

HTMLのドキュメントタイプはHTML5を使用する

HTML5での新要素は、article, aside, footer, header, hgroup, nav, sectionのみ使用する。

HTML5との互換性のないブラウザへの対応として、HTML5での新要素に対して装飾やスクリプトの使用を行わない。
また、HTML5での新要素が無視されても、なるべく暗示的にアウトラインが形成されるよう見出し要素を配置する。

上記は、HTML5と互換性のあるブラウザのみにしか対応しない場合には適応しない。

目的や機能に応じたHTML要素を使用する

アクセシビリティの向上、再利用性の向上、コード効率の向上のため、目的に応じたHTML要素を使用する。

HTMLの非推奨例 <div onclick="goToRecommendations();">All recommendations</div>
HTMLの推奨例 <a href="recommendations/">All recommendations</a>

仕様の曖昧な、定義リスト要素(dl, dt, dd)は使用しない。
その他、W3CよりHTML5に非推奨とされる要素、及び、仕様の曖昧な要素は使用しない。

装飾用途のみの要素(em, b, u)等は、範囲要素(span)で代替する。

マルチメディアには代替コンテンツを指定する

アクセシビリティの向上、再利用性の向上、リソースを取得・展開できない場合への対応のため、マルチメディアには代替コンテンツを指定する。

img要素であれば、alt属性を指定する。
しかし、目的が単に装飾的な画像の場合は、CSSの適応が遅延するため、alt=""のような代替テキストの指定は行わない。

HTMLの非推奨例 <img src="icon_circle.png" alt="" /><img src="title_example.png" />
HTMLの推奨例 <img src="icon_circle.png" /><img src="title_example.png" alt="タイトルの例" />

文書・装飾・動作を分離する

文書(HTMLファイル)・装飾(スタイリングファイル)・動作(スクリプトファイル)は、なるべく分離する。
また、HTMLファイルからスタイリングファイル・スクリプトファイルへのリンクは、なるべく減らす。

文書・装飾・動作を分離することで、管理や更新などを行いやすくする。
また、リンクを減らすことでリソースの取得通信回数を減らす。

HTMLの非推奨例 <!DOCTYPE html>
<html>
<head>
    <title>HTML sucks</title>
    <link rel="stylesheet" href="base.css" media="screen" />
    <link rel="stylesheet" href="grid.css" media="screen" />
    <link rel="stylesheet" href="print.css" media="print" />
</head>
<body>
    <h1 style="font-size: 1em;">HTML sucks</h1>
    <p>HTML is stupid!!</p>
</body>
</html>
  HTMLの推奨例 <!DOCTYPE html>
<html>
<head>
    <title>My first CSS-only redesign</title>
    <link rel="stylesheet" href="default.css" />
</head>
<body>
    <h1>My first CSS-only redesign</h1>
    <p>It’s awesome!</p>
</body>
</html>

実態参照文字を乱用しない

ファイル・エディタ、及び、製作者は、同じエンコーディング(UTF-8 BOMなし)を使用し、HTMLの中で特別な意味を持つ文字(<や&など)・コントロール(textarea要素への値の入力など)・見えない文字(&nbsp;など)を除き、実態参照文字を使用しない。

HTMLの非推奨例 The currency symbol for the Euro is &ldquo;&eur;&rdquo;.
HTMLの推奨例 The currency symbol for the Euro is “€”.

任意タグ・閉じタグは省略しない

HTML5でのタグ省略仕様は策定中であることと、他のHTMLドキュメントタイプとの互換性を保つため、任意タグ・閉じタグは省略しない。

ドキュメントタイプ宣言以外の空要素の末尾は、空要素の明示化、XHTML関連互換の向上のため />で閉じる。

HTMLの非推奨例 <!DOCTYPE html>
<title>abridgement</title>
<p>What will happen...
  HTMLの推奨例 <!DOCTYPE html>
<html>
<head>
    <title>Conventional</title>
</head>
<body>
    <p>Peace of mind</p>
</body>
</html>

スタイルシートとスクリプトのtype属性は省略しない

HTML5でスタイルシートとスクリプトはデフォルトの言語として扱われるためtype属性を省略可能であるが、コードの再利用性の向上、他のHTMLドキュメントタイプとの互換性を保つため、type属性は省略しない。

HTMLの非推奨例 <link rel="stylesheet" href="//www.example.com/style.css" />
<script src="//www.example.com/script.js"></script>
HTMLの推奨例 <link rel="stylesheet" href="//www.example.com/style.css" type="text/css" />
<script src="//www.example.com/script.js" type="text/javascript"></script>

HTMLの改行とインデント

要素のスタイリングとは独立して、ブロック、リスト、またはテーブル要素は、改行して新しい行を使用する。

ブロック、リスト、またはテーブル要素の子要素は、インデントする。

CSSにてdisplay: inline-block;が指定された要素同士の間の改行がブラウザに空白文字として扱われる場合などは、改行を取り除き一行にするか、改行をコメントアウトする。

HTMLの推奨例 <blockquote>
    <p><span>Space</span>, the final frontier.</p>
</blockquote>
<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>
<ul>
    <li>Moe</li>
    <li>Larry</li>
    <li>Curly</li>
</ul>
 
改行の無効化例 <ul><li>One</li><li>Two</li><li>three</li></ul>     <ul><!--
     --><li>One</li><!--
     --><li>Two</li><!--
     --><li>three</li><!--
 --></ul>

引用符

HTMLの引用符は、二重引用符を使用する。

HTMLの非推奨例 <a class='button-secondary'>Sign in</a>   HTMLの推奨例 <a class="button-secondary">Sign in</a>

CSSの引用符は、単一引用符を使用する。

CSSのURL指定には、引用符を使用しない。

CSSの属性セレクタの属性値検索文字列は、二重引用符を使用する。

CSSの非推奨例 a[href*='//www.example.com'] {
    font-family: "open sans", arial, sans-serif;
    background-image: url('//www.example.com/link_bg.png');
}
  CSSの推奨例 a[href*="//www.example.com"] {
    font-family: 'open sans', arial, sans-serif;
    background-image: url(//www.example.com/link_bg.png);
}

IDとclass名と独自データ属性名の命名規則

IDとclass名と独自データ属性名は、要素の目的や機能に応じた一般的で簡潔かつ意味明瞭な名前を、半角英小文字・半角数字と区切り文字に半角ハイフンを使用して命名する。

半角数字のみ・最初の文字列が半角数字・最初の文字列が半角ハイフンの命名を禁止する。

CSSにおけるアニメーション名などの命名規則も、上記に準じる。

非推奨例 yee-1901 button-green clear navigation atr-102 data-01
推奨例 step-1901 btn-secondary btn-clear-form nav-main author-102 data-length

CSSで擬似セレクタ以外はタイプセレクタと併用しない

タイプセレクタと擬似セレクタやヘルパークラスを除く他のセレクタとの組み合わせによるスタイリングは、セレクトパフォーマンスの低下、優先度の判定が困難になるため行わない。

CSSの非推奨例 ul#example {}
div.error {}
  CSSの推奨例 #example {}
.error {}

CSSの少数は省略しない

CSSのプロパティ値に1未満の数値を設定する場合には、CSS仕様上では小数点前の0を省略できるが、明示化のため省略しない。

CSSの色指定の16進数は6桁で記述する

CSSのカラープロパティ値に16進数を使用する際は、コードの再利用性を向上するため、6桁で記述する。

CSSの非推奨例 color: #ebc;   CSSの推奨例 color: #eebbcc;

CSSハックの使用は避ける

CSSハックの使用は、スタイルの適応範囲判定が困難になるため、極力避ける。

CSSプロパティの宣言順序

CSSプロパティは、ボックスモデル関連・ボックス範囲関連・ボーダー関連・テキスト関連・ボックス装飾関連・その他の順に宣言する。

上記のカテゴライズ内での宣言順は任意とする。

/* ボックスモデル関連 */
visibility: visible;
display: block;
position: relative;
top: 0;
right: 0;
bottom: 0;
left: 0;
float: none;
clear: both;
clip: auto;
overflow: auto;
z-index: auto;

 
/* ボックス範囲関連 */
box-sizing: content-box;
width: auto;
height: auto;
min-width: 0;
min-height: 0;
max-width: none;
max-height: none;
margin: 0 0 0 0;
margin-top: 0;
margin-right: 0;
margin-bottom: 0;
margin-left: 0;
padding: 0 0 0 0;
padding-top: 0;
padding-right: 0;
padding-bottom: 0;
padding-left: 0;
/* ボーダー関連 */
border: solid 1px #000000;
border-top: solid 1px #000000;
border-right: solid 1px #000000;
border-bottom: solid 1px #000000;
border-left: solid 1px #000000;
border-width: 0 0 0 0;
border-top-width: 0;
border-right-width: 0;
border-bottom-width: 0;
border-left-width: 0;
border-color: #000000;
border-top-color: #000000;
border-right-color: #000000;
border-bottom-color: #000000;
border-left-color: #000000;
border-width: solid solid solid solid;
border-top-width: solid;
border-right-width: solid;
border-bottom-width: solid;
border-left-width: solid;
-webkit-border-radius: 4px;
   -moz-border-radius: 4px;
        border-radius: 4px;
/* テキスト関連 */
font: italic normal bold 14px/22px 'MS Pゴシック';
font-size: 14px;
line-height: 22px;
text-indent: 0;
letter-spacing: 0;
word-spacing: normal;
font-style: normal;
font-variant: normal;
font-weight: normal;
font-family: 'MS Pゴシック';
text-align: left;
vertical-align: baseline;
color: #000000;
text-decoration: none;
text-transform: none;
white-space: normal;
word-break: normal;
word-wrap: normal;
overflow-wrap: normal;
text-shadow: 3px 3px 2px #0000ff;

 
/* ボックス装飾関連 */
background: url(bk.png) repeat scroll 0 0 transparent;
background-image: url(bk.png);
background-repeat: repeat;
background-attachment: scroll;
background-position: 0 0;
background-color: transparent;
background-clip: border-box;
background-size: auto;
background-origin: padding-box;
box-shadow: 10px 10px 10px 10px rgba(0,0,0,0.4) inset;

CSSの書式

最後のセレクタと宣言ブロックの間に、半角スペースを挿入する。

宣言ブロックを開始する中括弧は、セレクタと同じ行に記述する。

セレクタの記述された行とプロパティ宣言の行は改行し、同じ行に記述しない。

プロパティ宣言冒頭には、セレクタの記述より一つインデントする。

プロパティ名とコロンの間には、半角スペースを挿入しない。

プロパティ名後ろのコロンの後に、半角スペースを挿入する。

プロパティ宣言の行末に、セミコロンを付ける。

宣言ブロックを閉じる中括弧は改行し、プロパティ宣言と同じ行に記述しない。

宣言ブロックを閉じる中括弧は、セレクタの記述と同一のインデントを付与する。

擬似クラス・擬似要素には、シングルコロンを使用する。

改行・インデントの書式は、コードの可読性を向上させる場合、無視できるものとする。

CSSの書式例 .example_ul_{
____text-align:_center;
}
.example_ul_li_{
____display:_inline-block;
}
  書式無視の例 .example_ul_.one___{_width:_100px;_}
.example_ul_.two___{_width:__80px;_}
.example_ul_.three_{_width:_120px;_}
.example_ul_.four__{_width:_160px;_}

※ 上記の例は、アンダーバー(_)を空白文字(半角スペース)とした場合。

リセットCSSを使用する

リセットCSSとともに基本設定を記述し、スタイリングが重複しないよう配慮する。

以下、例。

例外

CMSやスクリプトなどによる自動出力は、例外とする。

他のプログラムとの互換性・コード品質・コーダーの互換性向上を目的とした例外を、製作者側製作責任者の了承を得ることで、追加できるものとする。

追加された例外は文書とし、当文書とともに保管する。


2016年01月29日 Webサイトif1tech管理人