Bicepper
コーディングに慣れてきたら、規約を作る必要が出てきますよね。
ルールもなしに好き勝手コーディングしていたら管理が大変になるのは目に見えてます。
もしコーディング規約に悩んでいるのならば、あの天下のGoogleが公開している規約を盗んじゃいましょう!
前置き
コーディングやプログラミングをしている時に、自分流で書いていて
プログラミング初心者
と思ったことありませんか?
一人でコーディング・プログラミングするなら自分流でも構いませんが、誰かと一緒にやる場合はコーディングルールを決める必要があります。
コーディングルールには、世に公開されているものから社内独自ルールなど様々ですが、今回はあの天下のGoogleが公開しているコーディング規約【HTML・CSS編】を日本語にしてみたいと思います。
Bicepper
それでは早速見ていきましょう!
1.背景
このドキュメントでは、HTMLおよびCSSのフォーマットとスタイルの規則を定義しています。
コラボレーションやコード品質の改善、およびインフラストラクチャのサポートの有効化を目標としています。
GSSファイルを含む、HTMLおよびCSSを使用した生のファイルに適用されます。
原則的にコード品質が維持されるのであれば、難読化、圧縮、コンパイルは自由に行えます。
2.全般
全般的なスタイルルール
プロトコル
可能であれば、埋め込みリソースにHTTPSを使用してください。
各種ファイルがHTTPS経由で利用できない場合を除き、画像やその他のメディアファイル、スタイルシート、およびスクリプトには常にHTTPS(https:)を使用してください。
非推奨
<!-- 推奨されません: プロトコルを省略 -->
<script src="//ajax.googleapis.com/ajax/libs/jquery/3.4.0/jquery.min.js"></script>
<!-- 推奨されません: HTTPの使用 -->
<script src="http://ajax.googleapis.com/ajax/libs/jquery/3.4.0/jquery.min.js"></script>
推奨
<!-- 推奨 -->
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.4.0/jquery.min.js"></script>
非推奨
/* 推奨されません: プロトコルを省略 */
@import '//fonts.googleapis.com/css?family=Open+Sans';
/* 推奨されません: HTTPの使用 */
@import 'http://fonts.googleapis.com/css?family=Open+Sans';
推奨
/* 推奨 */
@import 'https://fonts.googleapis.com/css?family=Open+Sans';
全般的なフォーマットルール
インデント
インデントは2スペースで一度に作成します。
インデントにタブを使用したり、タブとスペースを混在させたりしないでください。
<ul>
<li>Fantastic
<li>Great
</ul>
.example {
color: blue;
}
大文字
小文字のみを使用してください。
すべてのコードは小文字でなければなりません:これは、HTML要素名、属性、属性値(text/CDATAを除く)、CSSセレクター、プロパティ、およびプロパティ値(文字列を除く)に適用されます。
非推奨
<!-- 推奨されません -->
<A HREF="/">Home</A>
推奨
<!-- 推奨 -->
<img src="google.png" alt="Google">
非推奨
/* 推奨されません */
color: #E5E5E5;
推奨
/* 推奨 */
color: #e5e5e5;
末尾の空白
末尾の空白を削除してください。
末尾の空白は不要であり、差分を複雑にする可能性があります。
非推奨
<!-- 推奨されません -->
<p>What?_
推奨
<!-- 推奨 -->
<p>Yes please.
全般的なメタルール
エンコード
UTF-8(BOMなし)を使用してください。
エディターが、バイトオーダーマークなしで文字エンコードとしてUTF-8を使用していることを確認してください。
<meta charset=”utf-8″>を使用して、HTMLテンプレートおよびドキュメントのエンコーディングを指定します。
スタイルシートのエンコーディングはUTF-8を前提としているため、指定しないでください。
(エンコードの詳細と、指定するタイミングと方法については、HTMLおよびCSSでの文字エンコードの処理を参照してください。)
参考 https://www.w3.org/International/tutorials/tutorial-char-enc/W3Cコメント
可能であれば、必要に応じてコードを説明してください。
コメントを使用してコードを説明してください:「何をカバーし、どのような目的を果たし、それぞれのソリューションがなぜ使用される、または優先されるのか」
(完全に文書化されたコードを要求することは現実的ではないため、この項目はオプションです。マイレージは、HTMLコードとCSSコードで大きく異なる場合があり、プロジェクトの複雑さに依存します。)
アクションアイテム
TODOでTODOとアクションアイテムをマークしてください。
強調したいTODOのみ、キーワードTODOを使用し、@@などの他の一般的な形式を使用しないでください。
TODO(contact)のように、括弧内に連絡先(ユーザー名またはメーリングリスト)を追加してください。
TODO:action itemのように、コロンの後にアクションアイテムを追加してください。
{# TODO(john.doe): センタリングをあとで再考 #}
<center>Test</center>
<!-- TODO: オプションのタグを削除する -->
<ul>
<li>Apples</li>
<li>Oranges</li>
</ul>
3.HTML
HTMLのスタイルルール
ドキュメントタイプ
HTML5を使用してください。
HTML5(HTML構文)はすべてのHTMLドキュメントに推奨されます:<!DOCTYPE html>
(HTMLをtext/htmlとして使用することをお勧めします。XHTMLを使用しないでください。application/xhtml+xmlとしてのXHTMLは、ブラウザとインフラストラクチャ両方のサポート能力に欠いており、HTMLよりも最適化の余地が少なくなります。)
HTMLでは問題ありませんが、void要素を閉じないでください。これはつまり、<br />ではなく、<br>を記述します。
有効なHTML
可能な限り、有効なHTMLを使用してください。
目標パフォーマンスが達成不可能なほどのファイルサイズでない限り、有効なHTMLコードを使用してください。
「W3C HTML検証ツール」などのツールを使用してテストしてください。
参考 Nu Html Checkervalidator.w3.org有効なHTMLを使用することは、技術的な要件と制約に関する学習に役立つとともに測定可能なベースライン品質を保ち、適切なHTMLの使用を身につけられます。
非推奨
<!-- 推奨されません -->
<title>Test</title>
<article>This is only a test.
推奨
<!-- 推奨 -->
<!DOCTYPE html>
<meta charset="utf-8">
<title>Test</title>
<article>This is only a test.</article>
セマンティック
目的に応じてHTMLを使用してください。
作成された目的に合わせて要素(「タグ」と呼ばれることもあります)を使用してください。たとえば、見出しには見出し要素を、段落にはp要素、アンカーにはa要素などを使用します。
HTMLを目的に応じて使用することは、アクセシビリティ、再利用性、およびコード効率の理由から重要です。
非推奨
<!-- 推奨されません -->
<div onclick="goToRecommendations();">All recommendations</div>
推奨
<!-- 推奨 -->
<a href="recommendations/">All recommendations</a>
マルチメディアフォールバック
マルチメディアの代替コンテンツを提供してください。
画像、ビデオ、canvasを介したアニメーションオブジェクトなどのマルチメディアの場合は、代替アクセスを提供してください。画像の場合、意味のある代替テキスト(alt)の使用を意味し、使用可能な場合はビデオ、オーディオ、トランスクリプト、キャプションもです。
アクセシビリティの観点からも、代替コンテンツの提供は重要です:目の不自由なユーザーに対しては、@altなしで画像が何であるかを伝える手がかりがほとんどなく、他のユーザーの場合は、ビデオまたはオーディオのどちらであるかを理解する方法がないからです。
(alt属性が冗長性をもたらす画像や、CSSをすぐに使用できない純粋に装飾的な目的の画像については、alt=””のような代替テキストを使用しないでください。)
非推奨
<!-- 推奨されません -->
<img src="spreadsheet.png">
推奨
<!-- 推奨 -->
<img src="spreadsheet.png" alt="Spreadsheet screenshot.">
関心の分離
構造をプレゼンテーションと動作から分離してください。
構造(マークアップ)、プレゼンテーション(スタイリング)、および動作(スクリプティング)を厳密に区別し、3つの相互作用を最小限に抑えてください。
つまり、ドキュメントとテンプレートには、HTMLと、構造的な目的にのみ役立つHTMLのみが含まれていることを確認してください。プレゼンテーションのすべてをスタイルシートに、動作のすべてをスクリプトに移動してください。
さらに、ドキュメントとテンプレートから可能な限り少ないスタイルシートとスクリプトをリンクすることにより、接触領域をできるだけ小さくします。
構造をプレゼンテーションや動作から分離することは、メンテナンス上の理由から重要です。 スタイルシートとスクリプトを更新するよりも、HTMLドキュメントとテンプレートを変更する方が常に費用がかかるからです。
非推奨
<!-- 推奨されません -->
<!DOCTYPE html>
<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">
<h1 style="font-size: 1em;">HTML sucks</h1>
<p>I’ve read about this on a few sites but now I’m sure:
<u>HTML is stupid!!1</u>
<center>I can’t believe there’s no way to control the styling of
my website without doing everything all over again!</center>
推奨
<!-- 推奨 -->
<!DOCTYPE html>
<title>My first CSS-only redesign</title>
<link rel="stylesheet" href="default.css">
<h1>My first CSS-only redesign</h1>
<p>I’ve read about this on a few sites but today I’m actually
doing it: separating concerns and avoiding anything in the HTML of
my website that is presentational.
<p>It’s awesome!
エンティティ参照
エンティティ参照を使用しないでください。
同じエンコード(UTF-8)がファイルとエディター、およびチーム間で使用されると仮定した場合、&mdash;や、&rdquo;、&#x263a;などのエンティティ参照を使用する必要はありません。
唯一の例外は、HTMLで特別な意味を持つ文字(<や&など)に加えて、制御または「不可視」文字(改行なしスペースなど)の場合です。
非推奨
<!-- 推奨されません -->
The currency symbol for the Euro is &ldquo;&eur;&rdquo;.
推奨
<!-- 推奨 -->
The currency symbol for the Euro is “€”.
オプションのタグ
オプションのタグを省略してください(オプション)。
ファイルサイズの最適化とスキャンの可能性から、オプションのタグを省略することを検討してください。HTML5仕様は、どのタグを省略できるかを定義しています。
(このアプローチでは、ウェブ開発者に通常教えられるものとは大きく異なるため、より広いガイドラインとして猶予期間を確立する必要があります。一貫性とシンプルさの理由から、選択だけでなく、オプションのタグをすべて省略して提供するのが最適です。)
非推奨
<!-- 推奨されません -->
<!DOCTYPE html>
<html>
<head>
<title>Spending money, spending bytes</title>
</head>
<body>
<p>Sic.</p>
</body>
</html>
推奨
<!-- 推奨 -->
!DOCTYPE html>
<title>Saving money, saving bytes</title>
<p>Qed.
type属性
スタイルシートとスクリプトからtype属性を省略してください。
スタイルシート(CSSを使用しない場合を除く)およびスクリプト(JavaScriptを使用しない場合を除く)にtype属性を使用しないでください。
HTML5はデフォルトとしてtext/cssおよびtext/javascriptを含むため、これらのコンテキストでtype属性を指定する必要はありません。これは、古いブラウザでも安全に実行できます。
非推奨
<!-- 推奨されません -->
<link rel="stylesheet" href="https://www.google.com/css/maia.css" type="text/css">
推奨
<!-- 推奨 -->
<link rel="stylesheet" href="https://www.google.com/css/maia.css">
非推奨
<!-- 推奨されません -->
<script src="https://www.google.com/js/gweb/analytics/autotrack.js" type="text/javascript"></script>
推奨
<!-- 推奨 -->
<script src="https://www.google.com/js/gweb/analytics/autotrack.js"></script>
HTMLのフォーマットルール
全般的なフォーマット
すべてのブロック、リスト、またはテーブル要素に新しい行を使用し、すべての子要素をインデントしてください。
要素のスタイリングとは関係なく(CSSでは、要素がdisplayプロパティごとに異なる役割を担うことができるため)、すべてのブロック、リスト、またはテーブル要素を新しい行に配置します。
また、ブロック、リスト、またはテーブル要素の子要素である場合は、インデントしてください。
(リストアイテム間の空白に関連する問題が発生した場合、すべてのli要素を1行に入れることができます。Linterは、エラーの代わりに警告をスローします。)
<blockquote>
<p><em>Space</em>, the final frontier.</p>
</blockquote>
<ul>
<li>Moe
<li>Larry
<li>Curly
</ul>
<table>
<thead>
<tr>
<th scope="col">Income
<th scope="col">Taxes
<tbody>
<tr>
<td>$ 5.00
<td>$ 4.50
</table>
HTML行の折り返し
長い行を分割してください(オプション)。
HTMLには列の制限に関する推奨事項はありませんが、読みやすさが大幅に向上する場合は、長い行を折り返すことを検討できます。
行を折り返す場合、各継続行は元の行から少なくとも4スペース追加してインデントする必要があります。
<md-progress-circular md-mode="indeterminate" class="md-accent"
ng-show="ctrl.loading" md-diameter="35">
</md-progress-circular>
<md-progress-circular
md-mode="indeterminate"
class="md-accent"
ng-show="ctrl.loading"
md-diameter="35">
</md-progress-circular>
<md-progress-circular md-mode="indeterminate"
class="md-accent"
ng-show="ctrl.loading"
md-diameter="35">
</md-progress-circular>
HTML引用符
属性値を引用するときは、二重引用符を使用します。
属性値の前後には単一引用符(”)ではなく二重(“”)を使用します。
非推奨
<!-- 推奨されません -->
<a class='maia-button maia-button-secondary'>Sign in</a>
推奨
<!-- 推奨 -->
<a class="maia-button maia-button-secondary">Sign in</a>
4.CSS
CSSのスタイルルール
有効なCSS
可能な限り、有効なCSSを使用してください。
CSSバリデーターのバグに対処したり、独自の構文を必要としない限り、有効なCSSコードを使用してください。
「W3C CSS検証ツール」などのツールを使用してテストしてください。
参考 CSS Validation ServiceW3C有効なCSSを使用することは、技術的な要件と制約に関する学習に役立つとともに測定可能なベースライン品質を保ち、適切なCSSの使用を身につけられます。
IDとclassの命名
意味のある、または一般的なIDとclass名を使用してください。
プレゼンテーション名や暗号名の代わりに、問題の要素の目的を反映する、または一般的なIDおよびclass名を常に使用してください。
要素の目的を反映した具体的な名前は、最もわかりやすく、また変更される可能性が最も低いため、優先されるべきです。
汎用名は、特定の意味を持たない、または同胞と異なる意味を持たない要素の単なる代替です。通常、これらは「ヘルパー」として必要です。
機能名または汎用名を使用すると、ドキュメントまたはテンプレートが不必要に変更される可能性が低くなります。
非推奨
/* 推奨されません:無意味 */
#yee-1901 {}
/* 推奨されません:プレゼンテーション */
.button-green {}
.clear {}
推奨
/* 推奨:特定的 */
#gallery {}
#login {}
.video {}
/* 推奨:汎用的 */
.aux {}
.alt {}
IDとclass名のスタイル
できるだけ短く、長苦なる場合は必要な分だけIDとclass名を使用してください。
IDまたはclassが何であるかをできる限り簡潔に伝えてください。
このようにIDとclass名を使用すると、許容レベルな理解の可能性と、コード効率に貢献します。
非推奨
/* 推奨されません */
#navigation {}
.atr {}
推奨
/* 推奨 */
#nav {}
.author {}
タイプセレクター
タイプセレクタでIDおよびclass名を修飾することは避けてください。
必要な場合を除き(ヘルパークラスなど)、IDまたはclassと組み合わせて要素名を使用しないでください。
不要な祖先セレクターを避けることは、パフォーマンス上の理由で役立ちます。
非推奨
/* 推奨されません */
ul#example {}
div.error {}
推奨
/* 推奨 */
#example {}
.error {}
ショートハンド プロパティ
可能な場合は、ショートハンド プロパティを使用してください。
CSSは、1つの値のみが明示的に設定されている場合でも、可能な限りいつでも使用すべきさまざまなショートハンド プロパティ(fontなど)を提供します。
ショートハンド プロパティを使用すると、コードの効率と理解が容易になります。
非推奨
/* 推奨されません */
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;
推奨
/* 推奨 */
border-top: 0;
font: 100%/1.6 palatino, georgia, serif;
padding: 0 1em 2em;
0と単位
必要な場合を除き、「0」値の後に単位指定を省略してください。
必要でない限り、「0」の値の後に単位を使用しないでください。
flex: 0px; /* このflex-basisのコンポーネントにはユニットが必要です。 */
flex: 1 1 0px; /* ユニットなしでは曖昧ではありませんが、IE11では必要です。 */
margin: 0;
padding: 0;
先頭の0
値の先頭の「0」を省略してください。
値の前、または-1〜1の値の間に0を入れないでください。
font-size: .8em;
16進表記
可能な場合は、3文字の16進表記を使用してください。
許可される色の値の場合、3文字の16進表記は短く簡潔です。
非推奨
/* 推奨されません */
color: #eebbcc;
推奨
/* 推奨 */
color: #ebc;
プレフィックス
アプリケーション固有のプレフィックスを持つプレフィックスセレクター(オプション)。
大規模なプロジェクト、他のプロジェクトや外部サイトに埋め込まれるコードでは、IDおよびclass名にプレフィックス(名前空間として)を使用します。短い一意の識別子の後に、ダッシュ(-)を使用します。
名前空間を使用すると、名前の競合を防ぐことができ、検索や置換操作などでメンテナンスが簡単になります。
.adw-help {} /* AdWords */
#maia-note {} /* Maia */
IDおよびclass名の区切り文字
IDとclass名の単語はハイフンで区切ってください。
セレクター内の単語と略語をハイフン以外の文字(何も含まない)で連結しないでください。理解と可読性が向上します。
非推奨
/* 推奨されません:「demo」と「image」という言葉を分離していません */
.demoimage {}
/* 推奨されません:ハイフンの代わりにアンダースコアを使用しています */
.error_status {}
推奨
/* 推奨 */
#video-id {}
.ads-sample {}
ハック
ユーザーエージェントの検出とCSS「ハック」を避けてください。最初に別のアプローチを試してください。
ユーザーエージェントの検出や特別なCSSフィルター、回避策、ハックに関するスタイルの違いに対処するのは魅力的です。効率的で管理しやすいコードベースを達成し、維持するためには、両方のアプローチを最後の手段と見なす必要があります。
別の言い方をすれば、検出とハックにフリーパスを与えると、プロジェクトが抵抗を最小限に抑える傾向があるため、長期的にはプロジェクトを傷つけることになります。つまり、検出とハックを許可して使いやすくするということは、検出とハックをより頻繁に使用することを意味します。
CSSのフォーマットルール
宣言の順序
宣言をアルファベット順にしてください。
覚えやすく、保守しやすいコードを実現するために、宣言をアルファベット順に並べます。
ソートの目的でベンダー固有のプレフィックスを無視します。ただし、特定のCSSプロパティのベンダー固有の複数のプレフィックスはソートされたままにする必要があります(例:-mozプレフィックスは-webkitの前にあります)。
background: fuchsia;
border: 1px solid;
-moz-border-radius: 4px;
-webkit-border-radius: 4px;
border-radius: 4px;
color: black;
text-align: center;
text-indent: 2em;
ブロックコンテンツのインデント
すべてのブロックコンテンツをインデントしてください。
すべてのブロックコンテンツ、つまりルール内のルールと宣言をインデントして、階層を作り出すことで、理解力を向上させます。
@media screen, projection {
html {
background: #fff;
color: #444;
}
}
宣言停止
すべての宣言の後にセミコロンを使用してください。
一貫性と拡張性の理由から、すべての宣言はセミコロンで終了します。
非推奨
/* 推奨されません */
.test {
display: block;
height: 100px
}
推奨
/* 推奨 */
.test {
display: block;
height: 100px;
}
プロパティ名停止
プロパティ名のコロンの後にスペースを使用してください。
一貫性を保つために、プロパティと値の間には常に1つのスペースを使用してください(ただし、プロパティとコロンの間にはスペースを入れないでください)。
非推奨
/* 推奨されません */
h3 {
font-weight:bold;
}
推奨
/* 推奨 */
h3 {
font-weight: bold;
}
宣言ブロックの分離
最後のセレクターと宣言ブロックの間にスペースを使用してください。
常に、最後のセレクターと宣言ブロックを開始する開き中括弧の間に単一のスペースを使用してください。
開き中括弧は、特定のルールの最後のセレクターと同じ行になければなりません。
非推奨
/* 推奨されません:スペースがありません */
#video{
margin-top: 1em;
}
/* 推奨されません:不要な改行 */
#video
{
margin-top: 1em;
}
推奨
/* 推奨 */
#video {
margin-top: 1em;
}
セレクターと宣言の分離
セレクターと宣言を改行で区切ってください。
セレクタと宣言ごとに常に新しい行を開始します。
非推奨
/* 推奨されません */
a:focus, a:active {
position: relative; top: 1px;
}
推奨
/* 推奨 */
h1,
h2,
h3 {
font-weight: normal;
line-height: 1.2;
}
ルール分離
ルールを改行で区切ってください。
ルール間には常に空白行(2つの改行)を入れてください。
html {
background: #fff;
}
body {
margin: auto;
width: 50%;
}
CSS引用符
ルールを改行で区切ってください。
属性セレクターとプロパティ値には二重(“”)ではなく単一引用符(”)を使用してください。
URI値(url())に引用符を使用しないでください。
例外:@charsetルールを使用する必要がある場合は、二重引用符を使用してください。(単一引用符は使用できません)
非推奨
/* 推奨されません */
@import url("https://www.google.com/css/maia.css");
html {
font-family: "open sans", arial, sans-serif;
}
推奨
/* 推奨 */
@import url(https://www.google.com/css/maia.css);
html {
font-family: 'open sans', arial, sans-serif;
}
CSSのメタルール
セクションコメント
セクションコメントでセクションをグループ化します(オプション)。
可能であれば、コメントを使用してスタイルシートセクションをグループ化します。セクションを新しい行で区切ります。
/* Header */
#adw-header {}
/* Footer */
#adw-footer {}
/* Gallery */
.adw-gallery {}
5.別れの言葉
一貫してください。
もしあなたがコードを編集している場合は、数分かけて周囲のコードを見て、スタイルを決定してください。
他の人がすべての算術演算子の周りにスペースを使用している場合、あなたもそうすべきです。他の人のコメントにハッシュマークの小さなボックスがある場合は、あなたのコメントにもハッシュマークの小さなボックスがあるようにします。
スタイルガイドラインを持つことのポイントは、コーディングの共通の語彙を持ち、人々があなたの「言い方」ではなくあなたの「言っていること」に集中できるようにすることです。
ここでは、人々が語彙を理解できるようにグローバルスタイルルールを示しますが、ローカルスタイルも重要です。ファイルに追加するコードが、周囲の既存のコードと大幅に異なるように見える場合、読者が読みに行くときにリズムから外れます。これは避けましょう。
【まとめ】Googleのルールを真似してみよう
今回は、Googleのコーディング規約を紹介しました。
最後の別れの言葉は、短いですがとても重要です。
少しでも一貫性から外れると、後でとても面倒なことになります。リファクタリングも非常に面倒なものになるでしょう。
もしも自分のコーディングスタイルに疑問がある、もしくは確立していないのであれば、ぜひGoogleのコーディング規約を試してみてください!
Bicepper
ルールもしっかりとしていてわかりやすいですね。
自分流のルールを作るのもいいですが、まずは真似をしてみましょう!