本書には、../FBC_Press/STYLE_GUIDE.md をはじめとする FBC Press の共通ルールを適用します。このファイルでは、Sinatra 教科書に固有の判断だけを定めます。共通ルールと矛盾する場合は、FBC Press のルールを優先します。
- Sinatra の機能一覧ではなく、Web アプリケーションの仕組みを説明する。
- 各章で「Sinatra ではこう書く」だけで終えず、そのコードがどのリクエストを受け、どのレスポンスを返すのかを対応付ける。
- 映画図鑑を一章ずつ育て、最終章までに動作する完成形を示す。
- 課題との差別化を理由に、一般的な実装や完成コードを省略しない。
- FBC 固有の前提を本文へ持ち込まず、単独で読める OSS 技術書にする。
- 初めて使う仕組みは、必要になった場面で導入する。
- 先に使って後から名前を付ける場合は、読者が誤った理由付けをしない範囲に限る。リダイレクトは第2章と第5章で画面遷移として使い、第8章で PRG として意味付けする。
- HTTP は独立した知識として暗記させず、Chrome DevTools の Network タブで繰り返し観察する。
- REST は理論を網羅せず、リソース、URI、HTTP メソッドと CRUD の対応を実装に必要な範囲で説明する。
- Rack は Sinatra と Web サーバーをつなぐ位置を示すために扱い、インターフェースの詳細へ広げない。
- Ruby はダブルクォートを基本とし、本書内で統一する。
- 起動コマンドは
bundle exec ruby app.rbに統一する。 - Sinatra はクラシックスタイル（Classic Style）を使い、
enable :method_overrideを明記する。 - 利用者入力のエスケープには、
Rack::Utils.escape_htmlを呼び出すhヘルパーを使う。 - XSS の脆弱な例は第9章の説明中だけに置き、同じ章の中で安全なコードへ戻す。
- コードブロックには
ruby、erb、html、css、http、json、shなど実際の言語を指定する。 - 差分だけでは初学者が変更箇所を判断できない場合、対象ファイルの完成状態を示す。省略記号を含むコードを、そのまま動く完成コードのように見せない。
- 原稿中のコードとリポジトリ内のコードは一致させる。章完了時に原稿の手順どおり動作確認する。
- HTTP メソッドは
GET、POST、PATCH、DELETEのように大文字で書く。 - ステータスコードは、初出では
200 OK、303 See Other、404 Not Found、500 Internal Server Errorのように番号と理由句を併記する。 - 本文の HTTP メッセージ例は、読みやすい HTTP/1.1 形式を使う。HTTP/2 以降は通信時の内部表現が異なることを短く注記する。
- method override では、ブラウザが送るリクエストは
POSTであることと、Rack の処理後に Sinatra がPATCHまたはDELETEとして扱うことを区別する。 - リダイレクトは一つのリクエストの途中でページが切り替わるようには説明せず、リダイレクトレスポンスと、その後の新しい
GETリクエストを分けて説明する。
layout.erbだけが文書全体のhtml、head、bodyを持ち、個別ビューへ重複させない。- フォーム部品には、対応する
labelを用意する。 - 操作の意味がリンクか送信かを区別し、状態を変える処理を通常の
GETリンクにしない。 - 紹介文の改行表示には CSS の
white-spaceを使い、Ruby で<br>を生成しない。 - XSS は「危険な文字列」ではなく、出力先の HTML 文脈とエスケープの関係として説明する。
public/は公開される静的ファイルの置き場所とし、保存データはdata/movies.jsonに置く。
- 独立した部末演習は設けない。
- Network タブでの観察、入力値の変更、再読み込み、短いコード変更は、必要な説明の直後へ置く。
- 「確認しよう」「考えてみよう」などの見出しを毎章固定しない。
- 観察では、何を開き、どの項目を見て、何が確認できればよいかを明示する。
- 章の終わりには要約を繰り返さず、得た理解を次章の作業へつなげる。
- 各章末に
## さらに学ぶと## 参考資料を置く。 - 技術仕様は、使用中のバージョンに対応する公式ドキュメント、仕様書、RubyGems の情報を優先する。
- Chrome DevTools の画面名は、執筆時点の実画面で確認する。
- 外部資料を本文の代わりにせず、本章の範囲を越えて学びたい読者の導線として使う。
- 一般概念として本文に出す外来語は、原則としてカタカナ表記にする。例: アクセシビリティ、サイト、クラシックスタイル。
- 公式名、コード、ファイル名、HTTP メソッド、ヘッダー名、Chrome DevTools の画面ラベルは英語表記を残す。
- 初出で英語表記が理解に役立つ場合は、
クラシックスタイル（Classic Style）のようにカタカナを主表記にして英語を併記する。 - 同じ章の中で、同じ概念に英語表記とカタカナ表記を混在させない。画面ラベルとして引用する場合はバッククォートで囲む。