【テンプレート付き！】コメントを書く時のコツ

Forguncyでアプリを作っていると、最初は簡単だった構成も、気づけば複雑になってくるもの。
「この計算式、なんでこうしたんだっけ…？」
「誰がこのページ作ったの？」「どこを直したら影響でるの？」

そんなときに役立つのが、Forguncyの「コメント機能」です。

この記事では、Forguncyを使い始めたばかりの方に向けて、コメントの基本的な書き方と、実務での活用ポイントを紹介します。

コメントの書き方：3つのコツ

１．「なぜ」この処理をしているかを書く

「何をしているか」よりも、「なぜやっているか」を書く方が、後から見たときに役立ちます。

例）
×「ボタン押下時に変数を設定」
〇「ログイン後、初回アクセス時のみユーザー情報を初期化」

× 「受注日を設定」
〇 「新規登録時は、現在日付で受注日を自動設定（手入力の手間を減らす）」

２．短く、わかりやすく

長々と説明を書く必要はありません。
1文でOK。「～のため」「～の回避用」など目的が伝わると◎。

例）
「更新後に一覧へ戻るための遷移処理」
「管理者のみボタンを表示するための判定」
「未入力防止のため、初期値をセット」
「初回表示時のみ、一覧にフィルターをかけるため」

３．必要なところにだけ書く

Forguncyにはあらゆるところにコメントを残す機能がありますが、すべて使う必要はありません。
逆にあえてまとめて書いたほうが読みやすいこともあります。

目安としては、「ちょっと考えないと理解できなさそうな箇所」やボタンが配置されているセルやサーバーサイドコマンドの説明などに記載するのがすっきりします。

「説明」入力用テンプレート

サーバーサイドコマンドや再利用コマンドには、「説明」という項目でコメントが残せるようになっています。
どちらも汎用的な処理を用意して、使いまわすことが多い機能ですので、利用者が理解して使えるようにする必要があります。
そんなときに適切なコメントを用意しているとチーム開発が円滑に進みます。

説明テンプレート）

目的：
◯◯のためのデータ取得処理。

パラメーター：

• customerId：ログインユーザーのIDを設定
• fromDate / toDate：YYYY/MM/DD形式

戻り値：

• 注文リスト（OrderId, Date, Amount）

注意事項：

• 最大1,000件まで想定。超えると処理時間が増加。
• 月次処理と同時実行しないこと（デッドロックの可能性）

履歴：

YYYY/MM/DD 新規作成（担当：○○）

解説

① コマンドの目的（何をしているのか）

例：
「受注一覧画面で、指定された顧客IDの注文データを取得する」
「定期実行バッチ用。ステータス更新処理を一括で実行」

→ これは最低限。処理内容をざっくりまとめておく。

② 前提条件・パラメーターの想定

例：
「パラメータ 'CustomerId' は事前にログインユーザーのIDがセットされている必要がある」
「引数 'FromDate' 'ToDate' はYYYY/MM/DD形式」

→ 入力に何か制限がある／前提があるなら明記。
間違った入力が来ると処理が失敗するケースに備える。

③ 戻り値の概要

例：
「注文情報（OrderId, OrderDate, Amount）を含むテーブルを返す」
「'success' or 'error' の文字列を返却」

→ 使う側が受け取ったデータをどう使えばいいか理解しやすくなる。

④ 注意点・制限事項

例：
「データ件数が1,000件を超えるとパフォーマンスに影響あり」
「月次処理と同時に実行するとデッドロックの可能性あり」

→ 後から不具合が起きたときの原因特定がラクになる。

⑤ 修正履歴・バージョン情報（必要に応じて）

例：
「2025/06/10 パフォーマンス改善のためSQL修正（開発：○○）」
「v2対応に伴い、不要なパラメータを削除」

→ 変更履歴が追えるようにすると、保守性が上がる。
特にチームで開発しているときに有効。

まとめ

コメントはただのメモではなく、他人に引き継ぐ前提で書くのがベストです。
是非この機会に使ってみてはいかがでしょうか！