コーディングスタイル全般

動作環境や検証についての考え方

基本の検証ブラウザ

以下のブラウザ及びバージョンで閲覧に支障がない状態を確保します。

ブラウザ名	バージョン	OS
Google Chrome	最新バージョン	Microsoft WindowsまたはMac OS及びAndroid
Microsoft Edge	最新バージョン	Microsoft WindowsまたはMac OS
Mozilla Firefox	最新バージョン	Microsoft WindowsまたはMac OS
Safari	最新バージョン一つ古いメジャーバージョン最新	Mac OS及びiOS

Safariのメジャーバージョンは17.xの17の部分です。

検証についていくつかメモを残します。

クライアントからの要望でタブレットでの検証を依頼された場合は、タブレットとしての機能（キーボード、マウス、タッチを併用できる）を検証するのかどうかを確認してください
一部の検証機やモニターでのみ文字が段落ちするなどの指摘が入った場合はOSやブラウザの問題というよりも、画面の解像度の問題である可能性が高いので確認してください。複数のモニターで「おおよそ」問題がないことをエビデンスにユニークな解像度でも対応するかどうかを相談しましょう
Microsoft Windowsではモニタの表示スケールは初期値で125%となっていることがよくあります。その場合はデザインよりも125%大きく映ることになります。ビューポートに沢山の情報をいれることを重視している場合にMicrosoft Windowsの表示スケールを基準にすべきなのかはよく考慮してください

グレースフルデグラデーションで実装する

Graceful degradation (グレースフルデグラデーション) - MDN Web Docs 用語集: ウェブ関連用語の定義 | MDN

このガイドラインにおけるグレースフルデグラデーションの採用基準はBaselineとして採用されているかです。

ベースラインバッジの例

以下のサイトで、使用するAPIや機能がBaselineであるかが確認できます。

古くから機能しているAPIや普遍的な要素に関してはBaselineのバッジがついていないことがあるかもしれません。使おうとしている機能がガイドラインとして推奨できるかは、基本の検証ブラウザ全てで使用できるかを判断基準としてください。

このガイドラインでプログレッシブエンハンスメントよりもグレースフルデグラデーションを優先している理由は、主に次の点にあります。

モダンブラウザの整備が進んでいる

検証ブラウザとしているGoogle Chrome、Microsoft Edge、Mozilla Firefoxは、通常の設定であれば最新バージョンを使用することが可能です。また、最新バージョンのブラウザを使うことはセキュリティとエクスペリエンスの両面でユーザーにとって有益です。
Internet Explorerを検証対象から外した現在では、ブラウザのネイティブなAPIやCSSプロパティを使用することが堅牢性やメンテナンスコスト、パフォーマンス、アクセシビリティなど、ウェブサイトに必要とされるすべての場面で独自実装よりも有利に働きます。事情があり特異なバージョンや端末を使用するユーザーに対して対応するのと同様に最新のモダンブラウザーを使用するユーザーにとっても、提供できる最大のエクスペリエンスやパフォーマンスを提供することは重要だと考えています。

対応策の検討がしやすい

仮に検証範囲内の機能が使えないブラウザやデバイスに対応する必要がある場合、

フォールバックをネイティブな実装でできるものか
その機能がない状態でもコンテンツとして機能するか

という２つの検討事項から対応策を考えることができます（もちろんその限りではないこともあり得るでしょう）。基本の検証ブラウザを保証することで「どうしても」の場合のスコープを絞ることができ、全体的な作り直しが発生しづらくなります。

ネイティブファーストによる堅牢性

ブラウザネイティブな機能を優先して使用することでサイトが長持ちするはずです。ブラウザの多様性が縮小しているこのタイミングでは、ブラウザやデバイス間の差分吸収のための実装が少なくすむため、よりプロダクトのための実装に時間を使うことが可能になります。

ここからはファイルや言語によらず、共通して考慮すべきコーディングスタイルについて言及します。

文字コード

原則UTF-8（BOMなし）を設定します。

.editorconfigの設定

デフォルトの推奨設定 lint-tools/.editorconfig

チーム内で合意できれば

indent_style
indent_size

を変更しても構いませんが、YAMLファイルなどインデントがスペースである必要がある拡張子や言語を考慮し、そのままスペースを使用することが無難です。

YAML がタブを禁止するのはなぜですか?

タブは、エディタやツールによって扱いが異なるため、禁止されています。また、インデントは YAML の適切な解釈に非常に重要なため、この問題は取り組むことすら難しいほどです。実際、 Python の Guido van Rossum は、Python ソースでタブを許可することは多くの人にとって頭痛の種であり、Python をもう一度設計するならタブを禁止するだろうと認めています。
YAML Ain’t Markup Language

外部リソースの読み込み

以下の状況を除きCDNなど外部リソースを読み込むことは避けてください。

提供ベンダーがCDN以外の読み込み（ダウンロードなど）を制限している
多数のアクセスが見込まれるサービスのためWebフォントなどをオリジンサーバーに置くことが難しい
クライアントがセキュリティやパフォーマンス向上として導入しているCDNベンダー

読み込む必要がある外部リソースはhttps:~から始まるものを使用してください。

<!-- ⛔悪い例：httpから始まるURLを使用 -->
<link rel="stylesheet" href="http://example.com/styles.css">
<script src="http://example.com/script.js"></script>

<!-- ⛔悪い例：プロトコル相対URLを使用 -->
<link rel="stylesheet" href="//example.com/styles.css">
<script src="//example.com/script.js"></script>

<!-- 👍良い例：httpsから始まるURLを使用 -->
<link rel="stylesheet" href="https://example.com/styles.css">
<script src="https://example.com/script.js"></script>

ソース内のコメント

プロジェクトとして必要なコメント以外は記載しません。プルリクスト時に説明として必要だが、納品時に不要となるコメントがある場合は、コメントがなくともレビューが行えるようにするか、共有情報として適切に納品ソースに含めてください。

プロジェクトとして必要かどうかの判断基準は、リリース後1年たって新たなジュニアレベルの開発者がソースを触る際に必要な情報と考えてください。

プロジェクトとして必要となるコメントのケース

システム組み込みベンダーが存在する場合。対応者がパースしやすくするためにマークアップのブロックを指し示す
SSIやESIのインクルードコメント

CSS変数の実態

/* tokens */
--color-primary: #XXXXXX; /* ボタンとロゴの青みがかったブランドカラー */
--device-large: 1440; /* PCでの最大幅 */
--space-unit:1rem;
--space-xl: calc(3.25 * var(--space-unit)); /* 3.25rem,52px */

CSSにおける複雑で注意すべきセレクター指定をしていてレビューでコメントも添えることを指摘されたもの

  /* 注意：このセレクターは特定のレイアウト崩れを防ぐために必要です */
  .complex-selector > .specific-element:not(:last-child) {
      ...
  }

JSDoc
プルリクエストなどで、客観的に指摘された説明が必要とされるメソッドや文及び行
行単位でどうしても必要なlint ignore（プルリクエストでレビューし承認されたもの）
サードパーティライブラリのライセンスに関わる部分

レビュー時にレビュアーはコメントを精査します。
コメントの内容は第三者がわかるように記述します。必要であればリンクなどを入れ参照すべき資料などに導けるようにします。

ライセンス

ライブラリやフレームワーク（CSSリセットなども含む）を利用する際はライセンスを遵守します。

ライセンスが商用利用可能であることを確認しましょう。

ファイルパス

HTML、CSS、JavaScript内によらず外部リソースを読み込む際はルート相対パスを使用します。ルート相対パスに統一することで「サイト全体で一貫したパス指定ができる」というメリットがあります。
一部でもその他のパス記載ルールにしなければならない場合はチーム内で共有してください。

TypeScriptやNode.jsでのimportについてもTSConfigなどでエイリアスを設定し相対的なパスで読み込めるようにすることが望ましいでしょう。