中級エンジニア向け_レビュー観点×お客様説明ガイド_Node.js×React

中級エンジニア向け N o d e . js × R e a c t デ ス ク ト ッ プ ア プ リ ・ シ リ ー ズ コードレビュー観点 & お客様説明ガイド 実装できる人から、任せられる人へ 対象：実装経験1〜3年の中級エンジニア 内容：レビュー観点5つ＋お客様説明テンプレート

WHY なぜ「レビュー」と「お客様説明」を両方学ぶのか 動くコードが書けることと、任せられるエンジニアであることの間には、もう2段階ある。 実装力 レビュー観点 → 自分のコードを動かせる 他人のコードの品質を見極め、 チーム全体の質を底上げできる 説明力 → 技術的な判断を、 お客様が納得できる言葉に翻訳で きる このガイドは「レビュー観点」→「お客様説明」の順で、この2段階を埋める 2

RECAP 前提の共有：レビュー対象は3つの領域に分かれる Main Process Node.js領域 OS権限・ファイルI/O IPC境界 + プロセス間通信 セキュリティの要 Renderer Process + React領域 UI・状態管理 レビューで事故が起きやすいのは、この3領域の「境界」。次ページから境界を軸に5つの観点を見ていく 3

RE V IE W · 全体 方針 レビュー観点：5つの視点で見る 1 2 3 4 5 アーキテクチャ セキュリティ 状態管理 エラー処理 保守性 責務分離とIPC設計 IPC境界の安全性 State/Propsの一貫性 失敗時の振る舞い 命名・パフォーマンス 4

RE V IE W 1 · アー キテ クチ ャ 責務分離とIPC設計は適切か 見るポイント よくあるNGパターン ☐ Main側にUIロジックが漏れ出していないか ☐ Renderer側で直接Node.js APIを呼んでいないか ☐ IPCのチャンネル名が用途ごとに整理されているか ☐ 1つのIPCハンドラが複数の責務を持っていないか • Rendererからfsモジュールを直接requireしている • IPCチャンネル名が"do-something"のように曖昧 • Main側に画面表示用のフォーマット処理が書かれている 境界を越えた処理を見つけたら、まず「なぜここに書かれたか」を確認してからコメントする 5

RE V IE W 2 · セキ ュリ ティ IPC境界は安全に閉じているか 見るポイント 重点確認ポイント ☐ contextIsolationがtrueになっているか ☐ nodeIntegrationが不用意にtrueになっていないか ☐ IPCで受け取った値を検証せずファイルパスに使っていないか ☐ preloadスクリプトが必要最小限のAPIしか公開していないか • IPC経由の入力はすべて「信頼できない入力」として扱う • 任意のファイルパスをそのまま渡す実装は要注意 • contextBridgeで公開するAPIは一覧化してレビューする セキュリティ観点は「機能するか」ではなく「悪用できないか」で見る 6

RE V IE W 3 · 状態 管理 State/Propsの設計は一貫しているか 見るポイント 改善提案の型 ☐ • 同じデータが複数のコンポーネントでバラバラに保持されていな いか ☐ Propsのバケツリレーが3階層以上続いていないか ☐ useEffectの依存配列が正しく指定されているか ☐ ローカルStateとグローバルStateの使い分け基準があるか 「動きます」で終わらせず、次に触る人が迷わないかを 問う • 重複したStateはContextやカスタムフックへの切り出しを 提案 • 依存配列の指摘は、起きうる不具合とセットで伝える 7

RE V IE W 4 · エラ ー処 理 失敗時の振る舞いは設計されているか 見るポイント 指摘の伝え方 ☐ IPC通信の失敗（タイムアウト・例外）を考慮しているか • ☐ ファイル操作の失敗がユーザーに伝わる形で処理されているか ☐ catchブロックが握りつぶし（何もしない）になっていないか ☐ ログの粒度が本番運用で調査に使えるレベルか 「エラーが起きたらどう見えますか？」と動作を問う形 で指摘する • 握りつぶしは「意図的か、書き忘れか」を先に確認する • ログには再現に必要な情報（入力値・処理名）が入って いるか確認 8

RE V IE W 5 · 保守 性 半年後の自分・他人が読めるか 見るポイント パフォーマンスの初期チェック ☐ コンポーネント名・関数名が役割を表しているか ☐ • React DevToolsで再レンダリング回数をざっと確認する 不要な再レンダリングを招く実装になっていないか • Electronの起動時間・メモリ使用量に極端な増加がないか ☐ 大きくなりすぎたコンポーネントが分割候補になっていないか ☐ コメントが「なぜ」を説明しているか（「何を」だけになってい ないか） 見る • 最適化は「計測してから」が原則、先回りの最適化は指 摘に留める 9

RE V IE W · コメ ント の型 良いレビューコメントの型：事実→理由→提案 1 事実 「このIPCハンドラでは入力値の検証をしていません」 2 理由 「不正な値が渡された場合、ファイル操作に影響する可能性があります」 3 提案 「入力を検証する処理を追加するのはいかがでしょうか」 非難ではなく協働。「あなたのコード」ではなく「このコード」を主語にする 10

C L I E NT C O MM UN I C A T I O N · W H Y なぜ「お客様説明」が中級エンジニアの壁になるのか 1 技術的に正しい説明が、お客様には伝わらないことがある 2 「なぜ時間がかかるか」を専門用語なしで語る機会が増える 3 説明を誤ると、信頼だけでなく仕様認識のズレにつながる 合言葉：「技術的に正しい」と「相手に伝わる」は別のスキル 11

C L I E N T C O M M U N I C A T I O N · T EM P L A T E シーン別テンプレート 進捗報告 「〇〇機能は動作確認まで完了しています。残るは△△の調整で、予定どおり □日に完了見込みです」 仕様変更の相談 「ご要望を実現する方法は2つあり、それぞれ期間とコストが異なります。比較してご説明します」 不具合報告 「〇〇の操作で問題が発生することを確認しました。影響範囲は△△で、対応は □日を予定しています」 リリース案内 「今回のアップデートで、〇〇ができるようになります。操作方法に変更がある点は△△です」 12

C L I E N T C O M M U N I C A T I O N · B EF O R E / A F T E R NG例 → OK例：不具合報告の言い換え NG例 「RendererプロセスからIPCで渡した値がバリデーショ ンエラーになっていて、 Main側で catchされてました 」 → 専門用語が多く、お客様には状況も影響範囲も伝わらな い OK例 「入力内容のチェック処理で問題を確認しました。こ の画面をお使いの間だけ発生し、データが失われるこ とはありません。明日中に修正版をお届けします」 → 影響範囲・安全性・見通しの3点が、専門用語なしで伝わ る 13

S UM MA RY まとめ：中級エンジニアの次のステップ ✓ ✓ ✓ レビューは「粗探し」ではなく、境界（IPC）を軸に品質を底上げする行為 指摘は事実→理由→提案の順で、コードを主語にして伝える お客様説明は「技術的に正しい」を「伝わる言葉」に翻訳する別スキル 次のステップ：実際のPR・お客様報告のロールプレイで型を体に馴染ませる 14