1.かんたんな説明
ここに書いてあるのは、
コードをどう書くかを決める時に、
「何を大事にするか」を
まとめた考え方です。
ここに書いてあるのは、コードをどう書くかを決める時に、「何を大事にするか」をまとめた考え方です。 たとえば、
-
「わかりやすいほうがいい？」
-
「はやく作れるほうがいい？」
-
「あとで直しやすいようにするには？」
そんなことを考える時の、ヒントやルールのもとになるものです。
この文書は、あとで自分が読み返してもわかるように、なるべくくわしく書いています。だからすこしむずかしいところもあるけど、ひとつずつ読めばだいじょうぶです。
2.基本原則とは
基本原則は、
判断や行動の基盤となる
「考え方の土台」です。
基本原則とは、判断や行動の基盤となる「考え方の土台」です。この文書では、コードの書き方や設計判断の背景にある方針を指します。
原則とは、本来、物事を進める上で必ず守るべき根本的な決まりを指します。ここでは、「その決まりをどう定めるか」の拠り所となる基本原則を記述します。
3.目的と経緯
この文書の目的は、
将来の自分が読み返したときに、
記憶に頼らず
考え方や判断の背景を
思い出せるようにすることです。
この文書の目的は、将来の自分が読み返したときに、記憶に頼らず考え方や判断の背景を思い出せるようにすることです。
そのため、「決まりごと」だけでなく、本項のように「意図」や「経緯」も別途明記する方針を採ります。これは、以下の考えに基づいています：
-
決まりごとは、理解を深めずとも使える程度に、シンプルであるべき。
-
一方で、その決まりごとを見直す場合には、背後にある考え方の理解が不可欠である。
このように、用途の違いを明確にするため、「決まりごと」と「意図・経緯」は分けて記述します。
また、単なるメモや備忘録では、後から見返したときに内容が曖昧だったり、意図が不明瞭だったりすることが多いため、他者にも伝わる形で記述することを意識しています。結果的にそれが、自分自身の理解の整理にもつながると考えています。
4.このファイルの位置付けと使い方
この文書は、
将来の自分が読んで
理解しやすいように、
現在の判断や考え方の背景を
記録したものです。
この文書は、将来の自分が読んで理解しやすいように、現在の判断や考え方の背景を記録したものです。 他者にも分かりやすく書くことを心がけていますが、あくまで**「自分の思考の整理」が第一の目的**です。
実験的な方針や仮の原則も含まれており、そのまま実務に適用することは想定していません。実際に運用する場合は、環境に応じた調整が必要です。
5.この文書の扱い
この文書は、
「基本原則」と呼ばれる
ドキュメントのひとつです。
この文書は、「基本原則」と呼ばれるドキュメントのひとつです。「基本原則」は、設計や実装の際にどのように判断するかを整理するための、考え方の指針集です。
つまり、「ルール（決まり）」を定めるための「考え方（原則）」をまとめたものとして位置づけます。
そのため、プロジェクトや状況に応じて内容は見直され、随時更新される可能性があります。
6.内容
-
朝令暮改に注意
-
分かりやすさ重視
-
使いやすさは二の次
-
使用場所・用途を意識する
-
調べやすさ・変更のしやすさへの配慮
-
学習の視点
朝令暮改に注意
ここでは「分かりやすさ」を目的とした実験的な設計方針を採用しています。実務にはそのまま適用せず、状況に応じて調整が必要です。
分かりやすさ重視
記述した意図が伝わるようにします。開発物は多くの場合、目的を達成するための道具や手段であり、選ばれた理由には意味があります。意図が明示されていれば、修正・再利用がしやすくなり、過去の自分の記述を振り返ることも容易です。
開発速度を優先する場合には不要な考え方かもしれません。ただ、不具合調査なども考えると、「急がば回れ」で採用すべき考え方といえます。 結局、どの程度「分かりやすさを重視するか」が判断のポイントです。
ここでは、「分かりやすさ」を目的とした実験的な試みであるため、現場にそのまま適用することは想定していません。
使いやすさは二の次
「使いやすさ」も大切ですが、分かりやすさを最優先とします。つまり、「多機能だが覚えることが多い」といった状況は避けたいということです。
もちろん、分かりやすい命名・構造・機能を通じて使いやすさを高めることは重要です。
たとえば、記述意図を明確にするために、あえて多少使いにくくすることもあります。ここでは、**「使いやすさ」よりも「分かりやすさ」**を優先するという方針です。
使用場所・用途を意識する
たとえば、値の検査などは最小限にとどめ、処理速度にも配慮します。 そのために、前提条件を明確に記すことを基本とします。
個々のわかりやすさを追求しすぎると、全体にかかる負荷が大きくなります。こだわりすぎると、設計全体が破綻する可能性があるため、意識的にバランスを取ります。
調べやすさ・変更のしやすさへの配慮
分かりやすさに通じる考え方です。安易に処理をまとめると、途中経過が分かりづらくなることがあります。
また、コメントなどを過剰につけると、変更時にコメントも更新する必要があり、保守が煩雑になります。
それでもここでは、「分かりやすさ」を目的とした実験的な試みとして、あえてコメントを多めに記述しています。
その上で、どこまで可能か、どうすれば対応がしやすいかを検証する意図があります。
したがって、このまま実務に適用することは前提としていません。状況に応じた調整が前提です。
学習の視点
わかりきったことでも、あえて確認のために記述します。意外と文書化するとわかっていたつもりのことが書けないことが多いです。
7.要約
ChatGPTなどに前提条件として提示することを想定し、この文書の要点を以下にまとめます。
目的と経緯
- 将来の自分が、記憶に頼らず設計の考え方や判断理由を思い出せるようにすることが目的です。
-
単なるメモでは読み返したときに分かりにくいため、他者にも伝わる形式で記述しています。
→ その結果、自分自身の理解の整理にもつながると考えています。
内容の方針
- 分かりやすさを最重視します(後から読み返した時の理解のし易さを優先)。
- 使いやすさは二の次です(実用性よりも考え方の共有を重視)。
- 使用場面・用途を意識して記述します。
- 調べやすさ・変更のしやすさにも配慮します。
- 開発・運用にとどまらず、学習の視点も含めて構成しています。
文書の運用方針
- 本文書「基本原則」は、マークダウン形式で作成・管理します。
- 単なる備忘録ではなく、組織文書の形式で記述することを内部規約とします。
- 以下の文書をそれぞれ分けて作成します：
- 「コーディングルール(内部共通規約)」
- 「命名規則」
- 「構造設計」
技術的な運用指針
- Node.js（Gulp）を軸に、Pug、Sass、HTML（JavaScript）への設計方針の共有を行います。
- コードの直接流用ではなく、カスタマイズ可能な参考例としての共有を想定します。
- JSON等を使って外部データを共通化し、各種言語間（Pug、Sass、HTML等）でのデータ構造の一元管理を目指します。
ChatGPT向け文書
この文書は、将来の自分が判断や設計の背景を振り返れるよう、思考の整理と記録を目的としています。
「決まりごと」だけでなく、その意図や経緯も分けて記述することで、変更や再検討がしやすくなるようにしています。
方針は「分かりやすさ最重視・使いやすさは二の次」。対象や使用場面を意識し、調べやすさ・変更しやすさにも配慮しています。
内容には実験的な項目も含まれており、業務利用には調整が必要です。内部規約として管理し、命名規則・構造設計・ルールなどは別文書に分離しています。