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

投稿日: 2025.08.24 （更新日: 2025.08.26）

ガイドライン策定の背景・目的

私自身がコーディングする中で、日によって書き方が変わってしまったり、プロジェクトごとに書き方が異なってしまうことがよくあります。その度にどのような書き方がベストなのか悩んでしまうこともあります。

そのため、以下のような目的でコーディングガイドラインを策定しました。

一貫性のあるコードを書くため
コードの可読性と保守性を向上させるため
プロジェクトの品質を向上させるため
コーディングを作業効率を向上させるため

コーディング全般

対応ブラウザとデバイス

Browserslistのdefaults設定を参考に、以下のブラウザとデバイスをサポート対象とします。 https://browsersl.ist/#q=defaults

defaults設定では、以下の条件に該当するブラウザ・デバイスが対象となります：

> 0.5%：世界シェア^※0.5%以上のブラウザ・デバイス
last 2 versions：各ブラウザの最新2バージョン
Firefox ESR：企業や教育機関向けの長期サポート版
not dead：アップデートが停止していないブラウザ・デバイス

// package.json（抜粋）
"browserslist": [
  "defaults"
],

※なぜ日本シェアではなく、世界シェアなのか

日本シェアにしない理由は、サポートが古くなっているブラウザが多く、ユーザーの利便性を損なう可能性があるためです。そのため、世界シェアを基準にすることで、より多くのユーザーに対応できるようにしています。

例えば、2025年8月現在、既にPayPayなど様々なサービスがiOS 16.0未満のサポートを終了しています。
https://paypay.ne.jp/notice/20250404/f-01/

しかし、依然として日本シェアでは、iOS 15.0のシェアが0.5%以上を占めています。
https://browsersl.ist/#q=%3E+0.5%25+in+JP%2C+last+2+versions%2C+Firefox+ESR%2C+not+dead&region=JP

Browserslistによる日本のデバイスシェアを示した画像。2025年8月現在、iOS 15.6-15.8が0.69%のシェアを占めている。 — 2025年8月現在、Browserslistには依然としてiOS15のシェアが0.5%以上である。

文書型宣言

特別な理由がなければHTML Living Stardardの仕様に準拠とします。

<!DOCTYPE html>

エディター

エディターの指定

エディターの指定はしませんが、Visual Studio Code（以下、VSCode）を推奨します。

拡張機能のインストール

プロジェクトにインストール必須の拡張機能がある場合は、明示的に指定してください。例えば、VSCodeであれば.vscode/extensions.jsonに記載します。そうすることで、拡張機能の検索欄に@recommendedと入力することで、推奨されている拡張機能を一覧で確認できます。

文字コード

特別な理由がない限り⽂字コードはUTF-8（BOM なし）とします。

インデント

基本的なインデントは半角スペース2つを使用します。ただし、プロジェクトや言語の慣習に応じて、異なるスペース数を採用しても構いません。

改行コード（EOL）

改行コードは、lfとします。

その他ルール

行末には不要なスペースを入れないでください。
ファイルの末尾には必ず1行の改行を入れてください。（POSIX仕様に準拠）

ブレイクポイント

Tailwind CSS をベースに下記のブレイクポイントを使用します。

Breakpoint prefix	Minimum width	備考
xs	375px
sm	640px	SPからタブレットへの切り替え
md	768px
lg	1024px
xl	1280px	タブレットからPCへの切り替え
2xl	1536px
3xl	1920px

参考：https://tailwindcss.com/docs/responsive-design

assetsフォルダの配置場所

プロジェクトのルートにassetsフォルダを作成し、画像やフォントなどの静的アセットを格納します。

assets名	ファイルパス	備考
画像ファイル	/assets/images/配下	.jpg, .png, .webp, .svgなど
cssファイル	/assets/css/配下
JavaScriptファイル	/assets/js/配下
PDFファイル	/assets/pdf/配下
フォントファイル	/assets/fonts/配下	.woff2, .woff, .ttfなど
動画ファイル	/assets/videos/配下
データファイル	/assets/data/配下	.jsonなど

テキストの省略について

ファイル名での省略表記（例：image → img）は、HTML・CSS・JavaScriptなどの技術仕様で使用されている場合にのみ使用を認めます。それ以外では、可読性とメンテナンス性を重視し、省略せずに正式名称を使用してください。

命名規則について

ルートパス（/）は home と定義し、pagetop 機能との混同を避けるため toppage は使用禁止とします。

HTML

⽂書構造や⽂脈を理解し、マークアップ（意味付け）として最も最適なタグ（要素）を⽤いてマークアップしてください。

HTMLコーディングルール

HTMLコーディングルールは、html-eslintルールの推奨設定をベースとし、プロジェクトの要件に応じてカスタマイズしてください。また、フォーマッターはPrettierを使用してください。実装完了後は、Nu Html Checkerでの検証を行ってください。（※Nu Html Checkerの一部ルールは更新が遅れている場合があるので注意）

パスの記述

特に理由がなければ原則としてルートパスで記述してください。

<img src="/assets/images/foo.jpg" alt="">

メタデータ

title

Googleの検索結果ページでタイトルが途中で切れないように全⾓28 ⽂字以内としてください。

description

Googleの検索結果ページで説明⽂が途中で切れないように全⾓120⽂字以内とします。（ただし、スマートフォンでは全⾓50⽂字程度までしか表⽰されない）

CSS・SCSS

CSS設計について

下記4つの良いCSS設計の原則を守るようにしてください。

予測しやすい
再利用しやすい
保守しやすい
拡張しやすい

参考：【暫定】コーダー歴3年で辿り着いた保守しやすいコーディング手法

CSS設計手法について

CSS設計手法は、FLOCSSをベースとし、プロジェクトの要件に応じてカスタマイズしてください。

CSS・SCSSコーディングルール

CSS・SCSSコーディングルールは、stylelintルールの推奨設定をベースとし、プロジェクトの要件に応じてカスタマイズしてください。また、フォーマッターはPrettierを使用してください。

ルール名	Docsリンク	Rulesリンク	備考
① stylelint-config-recommended	Docsリンク	Rulesリンク
② stylelint-config-standard	Docsリンク	Rulesリンク	①の拡張
③ stylelint-config-recommended-scss	Docsリンク	Rulesリンク	②の拡張
④ stylelint-config-standard-scss	Docsリンク	Rulesリンク	①③の拡張

CSS・SCSSの記述方法について

クラスセレクターは分離せずに、必ず結合して記述してください。クラスセレクターを分離をすると検索に引っかからなくなり、影響範囲の把握が困難となるため保守性が下がります。

// 誤：下記のようにクラスセレクターを分離しないでください。
.foo {
  &_bar {}
}

// 正：クラスセレクターは結合して記述してください。
.foo_bar {}

プロパティの並び順について

CSS・SCSSのプロパティの並び順は、recessに準拠してください。

ヘルパークラスの実装について

ヘルパークラスの実装はTailwind CSSを利用してください。（※v4はSassに対応していないため、Sassを活用する場合はv3の利用を推奨）

JavaScript・TypeScript

JavaScript・TypeScriptコーディングルール

JavaScript・TypeScriptコーディングルールは、ESLintルールの推奨設定をベースとし、プロジェクトの要件に応じてカスタマイズしてください。また、フォーマッターはPrettierを使用してください。

json

jsonコーディングルール

jsonコーディングルールは、ESLint JSON Language Pluginルールの推奨設定をベースとし、プロジェクトの要件に応じてカスタマイズしてください。また、フォーマッターはPrettierを使用してください。

アクセシビリティ

不要な改行タグによるアクセシビリティの問題

<br />タグは文中に明示的に改行を挿入するために用意されたタグですが、多くの場合でデザイン目的で使用されています。そのため、スクリーンリーダーなどの支援技術を使用しているユーザーにとっては、不要な改行が挿入されることになり、読み上げの妨げになる可能性があります。この問題を回避するために、基本的に下記のように<br />タグにaria-hidden="true"属性を追加してください。

<br aria-hidden="true" />

もし段落を分けたい場合は、<br />タグではなく<p>タグを使用してください。

git

コミットメッセージのルール

prefix	説明	備考
add:	機能・ファイルなどを追加
fix:	コードやバグなどの修正（文字修正なども含む）
improve:	コードやパフォーマンスなどの改善
update:	パッケージやドキュメント、データなどの更新
remove:	ファイルやコードなどの削除
move:	ファイルやディレクトリなどの移動
chore:	上記のどれにも該当しないその他の変更（ビルド関連、ツール設定など）

制作環境

node

Node.jsのバージョン管理は、package.jsonでVoltaを使用して管理してください。

"volta": {
  "node": "20.12.2"
}

nodeバージョンの選び方

偶数バージョンを使用（LTSとなるため）
Active LTS または Maintenance LTS リリースのみ使用

Node.jsのメジャーバージョンは6か月間 Current ステータスとなり、ライブラリー開発者にサポートを追加する時間を与えます。6か月後、奇数のバージョン（9、11など）はサポートが終了し、偶数バージョン（10、12など）は Active LTS ステータスに移行し、一般公開向けの準備が整います。 LTS ステータスは「長期間サポート」であり、通常は合計30か月間の重大なバグ修正が保証されます。本番環境のアプリケーションでは Active LTS または Maintenance LTS スターテスのバージョンを利用する必要があります。

引用：https://nodejs.org/ja/about/previous-releases