Google HTML/CSS Style Guideを日本語化してみた

by Google HTML/CSS Style Guide

Google HTML/CSS Style Guide

HTML/CSSのスタイルGeneral Style Rules プロトコルProtocol
HTML/CSSのフォーマットGeneral Formatting Rules インデントIndentation
文字の大小Capitalization
文字列の後のスペースTrailing Whitespace
HTML/CSSのメタGeneral Meta Rules 文字エンコードEncoding
コメントComments
To DoAction Items
HTMLのスタイルHTML Style Rules 文書タイプDocument Type
HTMLの有効性HTML Validity
HTMLの意味Semantics
コンテンツの代替Multimedia Fallback
記述の分離Separation of Concerns
HTML EntityEntity References
オプションタグOptional Tags
type属性type Attributes
HTMLのフォーマットHTML Formatting Rules 全体のフォーマットGeneral Formatting
コーテーションマークHTML Quotation Marks
CSSのスタイルCSS Style Rules CSS Validity
IDとClassの名称設定ID and Class Naming
ID名、Class名ID and Class Name Style
タイプセレクタType Selectors
ショートハンドプロパティShorthand Properties
0の単位0 and Units
0.xの書き方Leading 0s
16進数Hexadecimal Notation
接頭辞Prefixes
ID、Class名の接続詞ID and Class Name Delimiters
Hacks
CSSのフォーマットCSS Formatting Rules プロパティの記述順序Declaration Order
ブロック毎のインデントBlock Content Indentation
プロパティの閉じ方Declaration Stops
プロパティ名の閉じ方Property Name Stops
宣言のかたまりDeclaration Block Separation
セレクタとプロパティの複数設定Selector and Declaration Separation
ルール同士の区切り方Rule Separation
CSSでのコーテーションCSS Quotation Marks
CSSのメタCSS Meta Rules 区切りコメントSection Comments

Important Note

Displaying Hidden Details in This Guide

This style guide contains many details that are initially hidden from view. They are marked by the triangle icon, which you see here on your left. Click it now. You should see “Hooray” appear below.
Hooray! Now you know you can expand points to get more details. Alternatively, there’s a “toggle all” at the top of this document.

背景Background

このドキュメントはHTMLとCSSの書き方のルールを定義します。コードのクオリティや可読性の向上を目的としています。これらの定義はHTMLとCSS(GSSを含む)で作成されるファイルに適用されます。コードのクオリティが維持される限り、ツールを使用して難読化や縮小化を行うことかできます。

This document defines formatting and style rules for HTML and CSS. It aims at improving collaboration, code quality, and enabling supporting infrastructure. It applies to raw, working files that use HTML and CSS, including GSS files. Tools are free to obfuscate, minify, and compile as long as the general code quality is maintained.

HTML/CSSのスタイルGeneral Style Rules

プロトコルProtocol

使用するリソースのプロトコルを省略する。

Omit the protocol from embedded resources.

http:とhttps:のどちらからでも双方のファイル(画像やその他のメディアファイル、スタイルシート、スクリプト)を参照できるよう、http:とhttps:と記述するプロトコルの記述を省略します。

Omit the protocol portion (http:, https:) from URLs pointing to images and other media files, style sheets, and scripts unless the respective files are not available over both protocols.

プロトコルを省略することで、違うプロトコルが混在する場合に起こりうる問題を防ぎ、ファイルサイズの縮小に貢献します。

Omitting the protocol—which makes the URL relative—prevents mixed content issues and results in minor file size savings.

HTML/CSSのフォーマットGeneral Formatting Rules

インデントIndentation

インデントには半角スペース2つを使用します。

Indent by 2 spaces at a time.

タブや、タブとスペースを組み合わせたインデントは使用しないでください。

Don’t use tabs or mix tabs and spaces for indentation.

文字の大小Capitalization

小文字のみを使いましょう。

Use only lowercase.

HTMLの要素、属性、属性値(テキスト/CDATAを除く)、CSSセレクタ、CSSプロパティ、CSSプロパティ値(文字列を除く)は小文字のみを使用して記述しましょう。

All code has to be lowercase: This applies to HTML element names, attributes, attribute values (unless text/CDATA), CSS selectors, properties, and property values (with the exception of strings).

文字列の後のスペースTrailing Whitespace

文字列の後にスペースは記述しないようにしましょう。

Remove trailing white spaces.

文字列の後のスペースは不要であり、ソースの可読性を低下させます。

Trailing white spaces are unnecessary and can complicate diffs.

HTML/CSSのメタGeneral Meta Rules

文字エンコードEncoding

BOMなしのUTF-8を使用する。

Use UTF-8 (no BOM).

お使いのエディタがの文字エンコードがUTF-8に設定されていることを確認してください。

Make sure your editor uses UTF-8 as character encoding, without a byte order mark.

HTML内では<meta charset="utf-8">として文字エンコードを指定します。

Specify the encoding in HTML templates and documents via <meta charset="utf-8">. Do not specify the encoding of style sheets as these assume UTF-8.

(その他、エンコードや指定方法は「HTMLとCSSにおける文字エンコード:Handling character encodings in HTML and CSS」を参照してください。)

(More on encodings and when and how to specify them can be found in Handling character encodings in HTML and CSS.)

コメントComments

Explain code as needed, where possible.
Use comments to explain code: What does it cover, what purpose does it serve, why is respective solution used or preferred?
(This item is optional as it is not deemed a realistic expectation to always demand fully documented code. Mileage may vary heavily for HTML and CSS code and depends on the project’s complexity.)

To DoAction Items

To DoはTODOを記述し、マークします。

Mark todos and action items with TODO.

@@等ではなく、TODOのみを使用して記述しましょう。

Highlight todos by using the keyword TODO only, not other common formats like @@.

TODOにはユーザー名やメーリングリストを括弧で囲み、添えておきましょう。

Append a contact (username or mailing list) in parentheses as with the format TODO(contact).

何をする必要があるかはTODOの後にコロンで区切って書きましょう。

Append action items after a colon as in TODO: action item.

HTMLのスタイルHTML Style Rules

文書タイプDocument Type

HTML5を使用する。

Use HTML5.

HTMLの構文は<!DOCTYPE html>を使用してHTML5として記述しましょう。

HTML5 (HTML syntax) is preferred for all HTML documents: <!DOCTYPE html>.

text/htmlとしてHTMLを使用することが推奨されています。XHTMLは使用しないでください。application/xhtml+xmlとしてのXHTMLはブラウザとインフラストラクチャのサポートが少なくHTMLよりも最適化に向いていません。

(It’s recommended to use HTML, as text/html. Do not use XHTML. XHTML, as application/xhtml+xml, lacks both browser and infrastructure support and offers less room for optimization than HTML.)

空要素はスラッシュで閉じないでください。例:<br />ではなく、<br>を使用する。

Although fine with HTML, do not close void elements, i.e. write <br>, not <br />.

HTMLの有効性HTML Validity

可能な限り有効なHTMLを使用する。

Use valid HTML where possible.

パフォーマンスの問題がある場合を除き、有効なHTMLを使用しましょう。

Use valid HTML code unless that is not possible due to otherwise unattainable performance goals regarding file size.

テストにはW3C HTML validatorのようなバリデーションツールを使用しましょう。

Use tools such as the W3C HTML validator to test.
Using valid HTML is a measurable baseline quality attribute that contributes to learning about technical requirements and constraints, and that ensures proper HTML usage.

HTMLの意味Semantics

意味に従ったHTMLを使用する。

Use HTML according to its purpose.

作られた意味に沿った要素(タグと呼ぶのは間違い)を使用しましょう。例えば、heading要素は見出しに、p要素は段落に、a要素はアンカーに使用します。

Use elements (sometimes incorrectly called “tags”) for what they have been created for. For example, use heading elements for headings, p elements for paragraphs, a elements for anchors, etc.

意味に沿ったHTMLを使用することはアクセシビリティ、再利用、コードの効率化の観点から重要となります。

Using HTML according to its purpose is important for accessibility, reuse, and code efficiency reasons.

コンテンツの代替Multimedia Fallback

マルチメディアコンテンツには代替を用意する。

Provide alternative contents for multimedia.

画像、動画、canvasを使用したアニメーションなどには、代替を記述しましょう。可能な限り、画像には代替テキスト(alt)、動画及び音楽にはトランスクリプトとキャプションを併記しましょう。

For multimedia, such as images, videos, animated objects via canvas, make sure to offer alternative access. For images that means use of meaningful alternative text (alt) and for video and audio transcripts and captions, if available.

代替コンテンツはアクセシビリティ上重要です。盲目のユーザーに対して画像を説明したり、動画や音楽を理解するのにも役立ちます。

Providing alternative contents is important for accessibility reasons: A blind user has few cues to tell what an image is about without @alt, and other users may have no way of understanding what video or audio contents are about either.
(For images whose alt attributes would introduce redundancy, and for images whose purpose is purely decorative which you cannot immediately use CSS for, use no alternative text, as in alt="".)

記述の分離Separation of Concerns

マークアップとスタイル、スクリプトを分ける。

Separate structure from presentation from behavior.

マークアップとスタイル、スクリプトを分け、相互干渉は最小限にしましょう。

Strictly keep structure (markup), presentation (styling), and behavior (scripting) apart, and try to keep the interaction between the three to an absolute minimum.

ドキュメントやテンプレートがHTMLのみで記述されているか確認しましょう。HTML以外のスタイル、スクリプトはスタイルシート等にまとめましょう。

That is, make sure documents and templates contain only HTML and HTML that is solely serving structural purposes. Move everything presentational into style sheets, and everything behavioral into scripts.

加えて、スタイルシートとスクリプトは必要なもののみを使用し、できるだけその数は少なくなるようにしましょう。

In addition, keep the contact area as small as possible by linking as few style sheets and scripts as possible from documents and templates.

メンテナンス性の面から、マークアップとスタイル、スクリプトを分けることは重要です。一般的に、スタイルとスプリクトが含まれているHTML文書を変更するのは、それぞれが分かれている文書を変更するよりもコストがかかります。

Separating structure from presentation from behavior is important for maintenance reasons. It is always more expensive to change HTML documents and templates than it is to update style sheets and scripts.

HTML EntityEntity References

HTML Entityを使用しない。

Do not use entity references.

文字エンコードにUTF-8を使用するのであれば—や”、☺といったHTML Entityは使用する必要はありません。

There is no need to use entity references like &mdash;, &rdquo;, or &#x263a;, assuming the same encoding (UTF-8) is used for files and editors as well as among teams.

ただ、例外としてHTMLで特別な意味を持つ文字(<や&など)はHTML Entityを使用しましょう。

The only exceptions apply to characters with special meaning in HTML (like < and &) as well as control or “invisible” characters (like no-break spaces).

オプションタグOptional Tags

オプションタグの省略(任意)

Omit optional tags (optional).

ファイルサイズの縮小やメンテナンス性向上のため、オプションタグを省略することができます。HTML5 specificationでどんなタグがオプションタグなのかを確認することができます。

For file size optimization and scannability purposes, consider omitting optional tags. The HTML5 specification defines what tags can be omitted.

(オプションタグの省略は広く一般に使用されていませんので、この手法が認知されるまでガイドラインへ含めるべきではないでしょう。)

(This approach may require a grace period to be established as a wider guideline as it’s significantly different from what web developers are typically taught. For consistency and simplicity reasons it’s best served omitting all optional tags, not just a selection.)

type属性type Attributes

スタイルシート、スクリプトのtype属性を省略する。

Omit type attributes for style sheets and scripts.

スタイルシートとスクリプトにはtype属性を使用してはいけません。

Do not use type attributes for style sheets (unless not using CSS) and scripts (unless not using JavaScript).

HTML5ではスタイルシートに使用されるtext/css、スクリプトに使用されるtext/javascriptは省略することができます。これは古いブラウザでも問題なく省略することができます。

Specifying type attributes in these contexts is not necessary as HTML5 implies text/css and text/javascript as defaults. This can be safely done even for older browsers

HTMLのフォーマットHTML Formatting Rules

全体のフォーマットGeneral Formatting

ブロック要素、リスト要素、テーブル要素は新しい行に記述し、子要素はすべてインデントさせる。

Use a new line for every block, list, or table element, and indent every such child element.

ブロック要素、リスト要素、テーブル要素(HTML5でのPhrasing content(文書内コンテンツ)以外)の要素を記述する場合は全ての要素で新しい行に記述しましょう。

Independent of the styling of an element (as CSS allows elements to assume a different role per display property), put every block, list, or table element on a new line.

また、ブロック要素、リスト要素、テーブル要素内に入る子要素にはインデントを設定しましょう。

Also, indent them if they are child elements of a block, list, or table element.
(If you run into issues around whitespace between list items it’s acceptable to put all li elements in one line. A linter is encouraged to throw a warning instead of an error.)

コーテーションマークHTML Quotation Marks

属性値を囲むコーテーションにはダブルコーテーションを使用する。

When quoting attributes values, use double quotation marks.

属性値を囲む場合はシングルコーテーションよりもダブルコーテーションを使用しましょう。

Use double ("") rather than single quotation marks ('') around attribute values.

CSSのスタイルCSS Style Rules

CSS Validity

Use valid CSS where possible.
Unless dealing with CSS validator bugs or requiring proprietary syntax, use valid CSS code.
Use tools such as the W3C CSS validator to test.
Using valid CSS is a measurable baseline quality attribute that allows to spot CSS code that may not have any effect and can be removed, and that ensures proper CSS usage.

IDとClassの名称設定ID and Class Naming

IDとClassには意味のある名前か一般的な名前を付ける。

Use meaningful or generic ID and class names.
Instead of presentational or cryptic names, always use ID and class names that reflect the purpose of the element in question, or that are otherwise generic.
Names that are specific and reflect the purpose of the element should be preferred as these are most understandable and the least likely to change.
Generic names are simply a fallback for elements that have no particular or no meaning different from their siblings. They are typically needed as “helpers.”
Using functional or generic names reduces the probability of unnecessary document or template changes.

ID名、Class名ID and Class Name Style

IDとClassの名前はできるだけ短いものとする。

Use ID and class names that are as short as possible but as long as necessary.
Try to convey what an ID or class is about while being as brief as possible.
Using ID and class names this way contributes to acceptable levels of understandability and code efficiency.

タイプセレクタType Selectors

ID、Classと一緒にタイプセレクタを使用しない。

Avoid qualifying ID and class names with type selectors.

必要不可欠である場合を除き、ID、Classセレクタは要素名を付加せずに記述しましょう。

Unless necessary (for example with helper classes), do not use element names in conjunction with IDs or classes.
Avoiding unnecessary ancestor selectors is useful for performance reasons.

ショートハンドプロパティShorthand Properties

プロパティはできるだけショートハンドプロパティで記述する。

Use shorthand properties where possible.

CSSでは値をまとめて記述することができ、できるだけそのように記述するべきです。

CSS offers a variety of shorthand properties (like font) that should be used whenever possible, even in cases where only one value is explicitly set.
Using shorthand properties is useful for code efficiency and understandability.

0の単位0 and Units

プロパティ値が0の場合は単位を省略する。

Omit unit specification after “0” values.

プロパティ値の0の後には単位を記述しないようにしましょう。

Do not use units after 0 values unless they are required.

0.xの書き方Leading 0s

プロパティ値が0で始まる場合は0を省略する。

Omit leading “0”s in values.

プロパティの値が-1から1の間に存在する場合は0を省略しましょう。

Do not use put 0s in front of values or lengths between -1 and 1.

16進数Hexadecimal Notation

16進数はできるだけ3文字で記述する。

Use 3 character hexadecimal notation where possible.

色を16進数で指定する場合は3文字で記述することができ、より短く簡単に指定することができます。

For color values that permit it, 3 character hexadecimal notation is shorter and more succinct.

接頭辞Prefixes

固有の接頭辞を付与する。(任意)

Prefix selectors with an application-specific prefix (optional).

大きなプロジェクトで使用するIDやClassには、他言語で使用されるような接頭辞(名前空間)を付与した名前にしましょう。接頭辞は短く、ユニークなものとし、接頭辞とID、Class名の間はハイフンでつなぎましょう。

In large projects as well as for code that gets embedded in other projects or on external sites use prefixes (as namespaces) for ID and class names. Use short, unique identifiers followed by a dash.

名前空間の使用は、ID、Class名の衝突を防止し、検索性の向上や置き換えやすくするなどメンテナンス性の向上を行うことができます。

Using namespaces helps preventing naming conflicts and can make maintenance easier, for example in search and replace operations.

ID、Class名の接続詞ID and Class Name Delimiters

ID、Class名の単語同士をハイフンでつなぐ。

Separate words in ID and class names by a hyphen.

セレクタで使用する単語同士は、単語をただ単につなげることやハイフン以外の文字でつなげることをしないようにしましょう。

Do not concatenate words and abbreviations in selectors by any characters (including none at all) other than hyphens, in order to improve understanding and scannability.

Hacks

Avoid user agent detection as well as CSS “hacks”—try a different approach first.
It’s tempting to address styling differences over user agent detection or special CSS filters, workarounds, and hacks. Both approaches should be considered last resort in order to achieve and maintain an efficient and manageable code base. Put another way, giving detection and hacks a free pass will hurt projects in the long run as projects tend to take the way of least resistance. That is, allowing and making it easy to use detection and hacks means using detection and hacks more frequently—and more frequently is too frequently.

CSSフォーマットCSS Formatting Rules

プロパティの記述順序Declaration Order

アルファベット順で記述する。

Alphabetize declarations.

プロパティは、覚えやすく、メンテナンスしやすいアルファベット順で記述しましょう。

Put declarations in alphabetical order in order to achieve consistent code in a way that is easy to remember and maintain.

この順序にはベンダープレフィックスは含まれませんが、ベンダープレフィックス自体はアルファベット順で記述(例:-mozを-webkitよりも前に記述する)しましょう。

Ignore vendor-specific prefixes for sorting purposes. However, multiple vendor-specific prefixes for a certain CSS property should be kept sorted (e.g. -moz prefix comes before -webkit).

ブロック毎のインデントBlock Content Indentation

ブロック毎にインデントを設定する。

Indent all block content.

ブロック毎にインデントを設定することで、階層を明確にし、メンテナンス性を向上させます。

Indent all block content, that is rules within rules as well as declarations, so to reflect hierarchy and improve understanding.

プロパティの閉じ方Declaration Stops

プロパティを設定したあとはセミコロンで閉じる。

Use a semicolon after every declaration.

コードの一貫性やメンテナンス性の観点から、各プロパティの終わりにはセミコロンを記述しましょう。

End every declaration with a semicolon for consistency and extensibility reasons.

プロパティ名の閉じ方Property Name Stops

プロパティ名とプロパティ値の間はスペースで開ける。

Use a space after a property name’s colon.

プロパティ名をコロンで閉じたあとはスペースを一つ開けてプロパティ値を記述しましょう。

Always use a single space between property and value (but no space between property and colon) for consistency reasons.

宣言のかたまりDeclaration Block Separation

最後のセレクタと宣言の間はスペースを一つ開ける。

Use a space between the last selector and the declaration block.

最後に記述されるセレクタと宣言の開始を表す括弧の間はスペース一つで開けましょう。

Always use a single space between the last selector and the opening brace that begins the declaration block.

宣言の開始を表す括弧は、最後に記述されるセレクタと同じ行に記述しましょう。

The opening brace should be on the same line as the last selector in a given rule.

セレクタとプロパティの複数設定Selector and Declaration Separation

セレクタとプロパティはそれぞれ別の行に記述する。

Separate selectors and declarations by new lines.

セレクタとプロパティを複数同時に記述する場合は、それぞれ別の行として記述しましょう。

Always start a new line for each selector and declaration.

ルール同士の区切り方Rule Separation

ルール同士は1行開けて記述する。

Separate rules by new lines.

ルール同士は連続した行で記述せず、1行開けましょう。

Always put a blank line (two line breaks) between rules.

CSSでのコーテーションCSS Quotation Marks

プロパティ値ではシングルコーテーションのみを使用する。

Use single quotation marks for attribute selectors and property values.

セレクタやプロパティ値ではダブルコーテーションではなくシングルコーテーションを使用しましょう。また、プロパティ値にURLを設定する場合はコーテーションは使用しないようにしましょう。

Use single ('') rather than double ("") quotation marks for attribute selectors or property values. Do not use quotation marks in URI values (url()).
Exception: If you do need to use the @charset rule, use double quotation marks—single quotation marks are not permitted.

CSSのメタCSS Meta Rules

区切りコメントSection Comments

CSSをグループで分け、区切りコメントを記述する。(任意)

Group sections by a section comment (optional).

可能な限りCSSはグループ毎に記述し、それぞれのグループに対してコメントを記述しましょう。

If possible, group style sheet sections together by using comments. Separate sections with new lines.

Parting Words

Be consistent.

If you’re editing code, take a few minutes to look at the code around you and determine its style. If they use spaces around all their arithmetic operators, you should too. If their comments have little boxes of hash marks around them, make your comments have little boxes of hash marks around them too.

The point of having style guidelines is to have a common vocabulary of coding so people can concentrate on what you’re saying rather than on how you’re saying it. We present global style rules here so people know the vocabulary, but local style is also important. If code you add to a file looks drastically different from the existing code around it, it throws readers out of their rhythm when they go to read it. Avoid this.

このエントリーをはてなブックマークに追加

0 件のコメント:

コメントを投稿