Webサイト制作におけるコーディング規約の作り方のポイント | ブログ | Glatch（グラッチ）

コーディング規約とは、HTMLやCSS、JavaScriptなどのWebサイトの制作に用いる各言語の記述ルールを定めたガイドラインです。ルールを定めておくことは品質の安定性や保守性を高め、外部協力者とのスムーズなやり取りを可能にします。

今回はコーディング規約の作成にあたって、押さえておきたいポイントをご紹介します。なお、本記事はWebサイト制作におけるコーディング規約を対象としています。

目的

まずは、コーディング規約を作成する目的を明確化することが大切です。制作者にはその人のポリシーやこだわりを本人が意識しているか否かに関わらず持っているものです。それを規約によってある程度矯正することになるので、窮屈に感じてしまう人もいます。その為、規約を守ることによって達成される目的を理解してもらうことは重要です。

共通ルール

HTML、CSS、JavaScript全てに共通するルールを記述します。

表示・動作保証ブラウザ（OS）

検証対象となるブラウザ（OS）を明示します。

規約例

本案件は、下記の環境にて正常に表示・動作することを保証する。

PC：Internet Explorer 10〜、Firefox最新バージョン、Google Chrome最新バージョン
SP：Android 4.0〜、iOS Safari最新バージョン

コメントの書式

コメントの書式を明示します。

規約例

コメントには/**/を使用し、//は使用しない。

/**************************************

ブロック名

***************************************/

/*-----------------------------------
モジュール名
-----------------------------------*/

/*-- 状態変化など --*/

画像ファイル

画像ファイルの使用可能な形式と命名規則を明示します。

規約例

使用可能な画像形式はJPEG（.jpg）、GIF（.gif）、PNG（.png）とする。

画像ファイルは種類に応じて下記に記す文言を接頭辞として、以降の文字列をアンダースコアで接続して命名する。

種類	表記
写真	img
ボタン	btn
アイコン	ico
テキスト	txt
バナー	bnr

ディレクトリ

ディレクトリの構造の指定、共通で読み込むファイルの格納先のディレクトリ名の指定（img、scriptsディレクトリなど）、開発ディレクトリと出力ディレクトリが別れている場合などを明示します。

規約例

各共通ディレクトリ名は以下とする。

種類	表記
画像ディレクトリ	images
CSSディレクトリ	styles
JavaScriptディレクトリ	scripts
開発ディレクトリ	src
出力ディレクトリ	dist

メタ

文字コード、ディスクリプション、キーワードなどメタ情報に関して記述事項があれば明示します。個人的には文字コードを明示するくらいです。

規約例

文字コードはUTF-8（BOMなし）とする。

HTMLに関するルール

基本ルール

マークアップを行う上での基本的なルールを明示します。

規約例

HTMLのバージョンはHTML5とする。
インデントは半角スペース2つとする。
JavaScriptの読み込みは、動作に影響がある場合を除いて</body>タグの直上とする。

head内に記述するコード

head内に記述するコードを明示します。

規約例

head内に記述するコードは下記を最低限とし、制作コンテンツに応じて指示があれば追加・変更する。

<head>
<meta charset="UTF-8">
<meta name="format-detection" content="telephone=no,address=no,email=no">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="description" content="description">
<link rel="stylesheet" type="text/css" href="../css/xxx.css">
<title>タイトル</title>
</head>

CSSに関するルール

基本ルール

セレクタの後のスペースの有無やプロパティの記述順などの基本的なルールを明示します。

規約例

インデントは半角スペース2つとする。
カラーコードは小文字とする。
サイズ単位はPCの場合はpx、スマートフォンの場合はremを用いる。
プロパティの記述順は以下とする（以下省略）。
idはJavaScript実装時のみ使用し、通常のCSSコーディングにはclassを用いる。

プリプロセッサ・タスクランナー

プリプロセッサまたはタスクランナーを用いる場合は明示します。併せて設定ファイル（package.json、gulpfile.jsなど）の共有をします。

規約例

本案件では、プリプロセッサおよびタスクランナーは下記を使用する。

プリプロセッサ：Sass
タスクランナー：Gulp

リセットCSS

ブラウザのデフォルトスタイルをリセットする場合、どのリセットCSS（あるいはノーマライズCSS）を使用するか、またはオリジナルのものがあれば明示します。

規約例

本案件では、リセットCSSはhtml5doctor.com Reset Stylesheet 1.6.1を使用する。

設計パターン（BEM、SMACSSなど）

BEMやSMACSSなどの設計パターンを用いる場合は明示します。

規約例

本案件では、設計パターンにBEMを用いる。

命名規則

規約例

idおよびclass名の命名規則を明示します。

本案件では、idおよびclass名の命名規則をBEMの規則に準ずる。ただし、JavaScriptのトリガーとして使用するidおよびclass名にはjs-の接頭辞を用いる。

JavaScriptに関するルール

使用ライブラリ

jQueryやReactなどのライブラリを使用する場合は明示します。

規約例

本案件では下記ライブラリを共通で読み込むこととする。

jQuery 2.2.0
Underscore.js 1.8.3

デザインパターン

シングルトンやモジュールパターンなどのデザインパターンを統一して用いる場合は明示します。ごく稀ですがデザインパターンを指定される事があります。

規約例

本案件ではシングルトンパターンを用いた設計を行う。

禁止事項

これだけはやらないで欲しい事項を記述します。コーディング規約に具体的に明示されていないコーディングをする場合、禁止事項を明示していれば大きな間違いは犯すリスクを軽減することが出来ます。

ここでは説明の為に独立した項目にしていますが、各項目の中に禁止事項項目を設けて記述しても良いと思います。ただ、禁止事項を多くしすぎると制作者のモチベーションを下げたり、逆に保守性の低下などを招く恐れがあるので、必要最低限に留めるべきです。

規約例

画像パスは絶対パスで記述してはならない。
セレクタのネストを3階層以上にしてはならない。
セレクタにid、class名と共に要素名を付与してはならない。
HTML内にインラインでCSSまたはJavaScriptを記述してはならない。

まとめ

コードの統一性は、チームやWebサイトの規模が大きくなればなるほど重要です。その為にもコーディング規約を用意しておき、品質を担保しておく事は長期的視点から考えれば是が非でも用意しておきたいものです。

参考文献

Google HTML/CSS Style Guide