LoginSignup
12

More than 5 years have passed since last update.

GitHub Styleguide を訳してみた(HTML & Templates編)

Last updated at Posted at 2014-10-12

GitHubによるコーディングスタイルガイドのうち、マークアップやテンプレート(エラーページ)に関わるものを翻訳してみました。原文はこちらにあります。

そのうちRuby編やJavaScript編にも手を付けていこうと思います。

追記

Ruby編を作りました。


0.マークアップとテンプレート

Doctype 宣言

ブラウザが標準モードをトリガするように、適切なdoctypeを使う必要があります。互換モードは常に避けるべきです。

簡単のために、私たちはhtml5 doctypeを使います。

<!DOCTYPE html>

コーディングスタイル

汎用的なフォーマット

  • 文章における段落は、常に<p>タグを使います。<br>タグを複数使ってはいけません。
  • リスト形式の要素は常に<ul><ol>もしくは<dl>を使います。<div><p>を組み合わせて使ってはいけません。
  • 入力フォームに文章が付随する場合、特にラジオボタンやチェックボックス要素において<label>タグを使います。
  • タグの属性はクォートで囲まずに記述することができますが、可読性のために属性をクォートで必ず囲みます。
  • <!-- /.element -->のように、閉じタグにコメントで目印をつけるのは避けましょう。ページのロード時間が増えるだけですし、ほとんどのエディタにはインデントガイドや開始/閉じタグのハイライト機能がついているからです。
  • <br><hr><img>やなど、空要素のタグにスラッシュをつけることは避けます。
  • tabindexを記述するのは避け、順序の設定はブラウザに依拠するようにします。
<p class="line-note" data-attribute="106">This is my paragraph of special text.</p>

ブール値属性

多くの属性においては、disabledcheckedなどの値が設定は必須ではないので、設定はしないようにしましょう。

<input type="text" disabled>

<input type="checkbox" value="1" checked>

<select>
  <option value="1" selected>1</option>
</select>

より詳しい情報についてはWhatWG sectionを参照してください。

リーンなマークアップ

HTMLを書くときは、余計な親要素は出来るかぎり使わないようにします。繰り返しの作業やリファクタリングを必要とする反面、出力するHTMLは少なくなります。以下がその例です。

<!-- 悪い -->
<span class="avatar">
  <img src="...">
</span>

<!-- 良い -->
<img class="avatar" src="...">

フォーム

  • セレクトボックスよりも、ラジオボタンやチェックボックスを使う方が好ましいです。
  • ラジオボタンやチェックボックスは、それぞれ<label>で囲みます。for属性がなくても、囲まれた要素は自動的にひも付きます。
  • フォームのボタンは常にtype属性をもつべきです。プライマリなボタン(もっとも重要なボタン)をtype="submit"とし、ほかのボタンはtype="button"としましょう。
  • 特に複数の送信ボタンが存在するフォームにおいては、プライマリなボタンがDOM構造の最初に来るようにします。各ボタンの表示上の順序はfloat: right;によって維持します。

テーブル

<thead><tfoot><tbody><th>タグ(とscope属性)を適切な箇所で使います。(<tfoot><tbody>より先に来ていることに注意しましょう。ブラウザにデータが入った表を読み込ませる前にフッターをロードさせるためです。)

<table summary="2011年請求書一覧">
  <thead>
    <tr>
      <th scope="col">表ヘッダー 1</th>
      <th scope="col">表ヘッダー 2</th>
    </tr>
  </thead>
  <tfoot>
    <tr>
      <td>表フッター 1</td>
      <td>表フッター 2</td>
    </tr>
  </tfoot>
  <tbody>
    <tr>
      <td>表データ 1</td>
      <td>表データ 2</td>
    </tr>
  </tbody>
</table>

1. ページタイトル

GitHubのページには基準となる<title></title>が存在します。サインアウトした状態のページには.GitHubが最後に付きます。サインインしたユーザからはGitHubは消えます。

一般的なページ

ほとんどのページでは以下のフォーマットに沿います。

THING ・ WHO ・ GitHub

例:Pull Requests ・ rails/rails ・ GitHub

プロフィールページ

プロフィールページでは、デベロッパーがUSERNAMEFULL NAMEを設定している場合、それらを含みます。

USERNAME (FULL NAME) ・ GitHub

例:jonrohan (Jon Rohan) ・ GitHub

リポジトリページ

リポジトリのページでは、そのリポジトリのOWNERREPOSITORYのタイトルを含みます。

OWNER/REPOSITORY ・ GitHub

例:twitter/bootstrap ・ GitHub

2.エラーページ

エラーページは、スクリプトやJavaScriptなどを一切使わず、またどんな依存ももたないように構築されているべきです。つまり、静的なHTMLとインラインのCSS、そしてbase64エンコードの画像のみで作られているべきです。

以下の要素はどのエラーページにおいても使用が禁じられています:

  • src属性をもった<script>タグ
  • 外部データをロードするJavaScript
  • <link>タグ
  • srcがURLを指す<img>タグ

テンプレートリスト

個別の目的に沿ったテンプレートページを複数用意しています。

  • 500 – 例外が発生しリカバリできなかった

  • 502 – ユニコーン! ページがタイムアウトになった

  • 503 – ユニコーン! 問題が発生しアプリケーションサーバと通信ができない

  • 404 – Not found

  • 404(Pages)Pages 用のNot found

  • 410 – 削除された機能

  • 422 – リクエストに対してNginxがレスポンスできないとき

  • maintenance – メンテナンスを行うためにウェブサイトを落としているとき

ところで

Repro株式会社では一緒に切磋琢磨できる仲間を募集しています。 ぜひこちらをごらんください!

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
12