manabuyasuda / coding-guidelines Goto Github PK

View Code? Open in Web Editor NEW

158.0 8.0 37.0 103 KB

コードの最低限の品質を保つためのガイドラインです。

License: MIT License

html css image guidelines ecss

coding-guidelines's Introduction

コーディングガイドライン

このドキュメントはコードの最低限の品質を保つためのガイドラインです。プロジェクトに応じて内容を変更してもかまいません。

目的

このガイドラインの目的は以下の通りです。

コードの最低限の品質を担保すること
コーディングのルールを統一することによって保守性を向上すること
ドキュメント化することによって教育コストを減らすこと
コードの品質を向上するための土台にすること

coding-guidelines's People

Contributors

Stargazers

Watchers

coding-guidelines's Issues

Gitのコミットメッセージについてのガイドラインを追加する

Add: SVGのガイドラインを追加する

https://github.com/manabuyasuda/styleguide/blob/master/svg-operating-rules.md

クラス名リストに追加するUI

popup-window - dialogの類語で、リンク先を別の小さなウィンドウで表示するインターフェイス。
lightbox - carouselの類語で、モーダルのjQueryプラグインのこと。主な用途はサムネイル画像をクリックしてモーダルを開き画像を大きく見せること。
global-navigation - ほとんどの画面で表示されている、主要なナビゲーション。
local-navigation - あるカテゴリ内専用のナビゲーション。グローバルナビゲーションの中や下に配置する場合や、サイドバーに配置する場合がある。
mega-menu - 深い階層のカテゴリやページへのナビゲーション。ドロップダウン（クリックやマウスオーバー）で階層を表示していく。カテゴリやページ数の多いサイトのグローバルナビゲーションに使われることが多い。
linear-navigation - その画面の前後に移動するためのナビゲーション。ページネーションとの違いはページ指定ができないこと。
input - フォームの入力画面。
confirm- フォームの確認画面。
finish - フォームの完了画面。
text-field - input[type="text"]のような利用者が編集する改行なしのテキストフィールド。
textarea - textareaのような利用者が編集する複数行のテキストフィールド。
checkbox - input[type="checkbox"]のような1つ以上の項目を選択するインターフェイス。
radio - input[type="radio"]のような1つの項目を選択するインターフェイス。
select - selectのような1つの項目を選択するインターフェイス。ラジオボタンと違い、（dropdownのように）項目が最初は隠れているのが特徴。
submit - 送信ボタン。
reset - リセット（取り消し）ボタン。
modify - 修正ボタン。

Update: コミットメッセージのBodyについて説明を追加する

自己文書化（コメントがなくてもコードの意図が分かる）の状態がベストですが、それが難しい場合はコメントをコードに残します。
わざわざコミットメッセージを探すより、コードの説明はコードに残したほうがいいですよね。

コミットメッセージに何をしたのかを残すこともできます。ただし、コード側でも充分に説明するようにしてください。

Add: JSのガイドラインを追加する

Airbnb JavaScript Style Guide（日本語訳）をベースとする。

ES5のガイドライン（日本語訳）

Gitのコミットメッセージのガイドラインを追加する

tableタグの注意点（scope、colspanとrowspan）にcolgroupとrowgroupなどを追加

thを連結している場合はscope="rowgroup"かscope="colgroup"も指定する
colgroupの使い方

https://www.w3.org/WAI/tutorials/tables/irregular/

Update: ルールの優先度を追加する

必須：使用しなければエラーに繋がるようなもの、ほとんどの場合でベストプラクティスとなるもの。
強く推奨：ほとんどの場合でベストプラクティスとなり得るもの。遵守しない場合はその理由を協議、明記する必要がある。
推奨：いくつかのルールの中で特に推奨しているもの。

aria-*属性を使用するの修正

aria-currentについて。
locationの用途について、解釈の仕方によっては微妙？なこともあるため、汎用的なtrueを使用する。

navタグを効果的に使うにaria-labeledbyなどの項目を追加

aria-labelとaria-labeledbyを使う場合の例
navタグを使うシチュエーション

Update: Gitガイドラインの前提を提示する

WIPを使ったフローの場合にコミットメッセージが使えない・足りなくなる
- 1コミット1対応を前提としたフローに限定する
Gitといっても、様々な環境で使われるので、網羅することが難しい
- GitHubとBacklogを前提として、CLIはオプションにする

SVGをwidth: 100%;にするバグフィックスを削除する

このバグに当てはまることがなかったため。

Update: SVGの必須属性を見直す

https://qiita.com/manabuyasuda/items/01a76204f97cd73ffc4e#comment-45be7f082d411d5b8cff

SVG に詳しくなく、また、仕様書を読んでいないので不確かなコメントで恐縮なのですが、次の箇所が気になりました。

必須の属性を確認する
タグで必須の属性です。表示崩れの原因にもなるので、必ず指定してください。

xmlns="http://www.w3.org/2000/svg"（SVG名前空間宣言）
xmlns:xlink="http://www.w3.org/1999/xlink"（XLink名前空間宣言）
version属性
width属性とheight属性（pxは省略可）
viewBox属性

単に「必須」の定義が異なるだけかもしれませんが、これらには仕様上の必須（required, must）ではなく、実装を考慮した推奨（recommended, should）も含まれているのではないかなと思いました。

xmlns 属性は HTML に SVG をインラインで記述する場合は省略可能
xmlns:xlink 属性は svg 要素の子孫要素で xlink:href 属性などを使用する場合は必須
version 属性はたしかに指定したほうが良さそうですが、必須なのでしょうか？
width 属性と height 属性は省略可能（省略した場合は不定扱い？）
viewBox 属性は省略可能（省略した場合は svg 要素の表示領域になる？）