コーディング規約に迷ったら天下のGoogleから盗め【雛形】

コーディング規約に迷ったら天下のGoogleから盗め【雛形】

しんぺい

こんにちは!しんぺいです。

コーディングに慣れてきたら、規約を作る必要が出てきますよね。

ルールもなしに好き勝手コーディングしていたら管理が大変になるのは目に見えてます。

もしコーディング規約に悩んでいるのならば、あの天下のGoogleが公開している規約を盗んじゃいましょう!

前置き

コーディングやプログラミングをしている時に、自分流で書いていて

プログラミング初心者

この書き方でいいのかな…心配になってきたぞ

と思ったことありませんか?

一人でコーディング・プログラミングするなら自分流でも構いませんが、誰かと一緒にやる場合はコーディングルールを決める必要があります。

コーディングルールには、世に公開されているものから社内独自ルールなど様々ですが、今回はあの天下のGoogleが公開しているコーディング規約【HTML・CSS編】を日本語にしてみたいと思います。

しんぺい

かなり長いので、最初は気になるところや自分が理解できるところだけ読むのでも全然ありです!

それでは早速見ていきましょう!

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のコーディング規約を試してみてください!

しんぺい

さすがGoogle!

ルールもしっかりとしていてわかりやすいですね。

自分流のルールを作るのもいいですが、まずは真似をしてみましょう!