みなさんちゃんとドキュメント書いていますか？
私は日頃からドキュメントの作成を心がけているのですが、以前ふと思いついて作成したドキュメントが結構良かったのでそれを共有しに来ました。
環境変数をドキュメント化する
タイトルの通りですが、プロジェクト(≒リポジトリ,アプリケーション毎)で利用する環境変数の一覧をドキュメント化しておきませんか？という提案です。
私は実際に下記のようなドキュメントを作成しています。
概要
XXXXXプロジェクトで利用する環境変数のまとめ
ローカルでの設定は .env.example から .env を作成すること
注意！
認証トークンなど、秘匿すべき情報の実体は 絶対にここに書いてはならない
秘匿すべき情報はその取得元のリンク等の記述にし、リンク先のサービスで権限がないと参照できないよう運用すること
秘匿すべきかどうか迷ったら、実体を書かず大人しくリンク等の記述にしてください
環境変数一覧
| 変数名 | 利用箇所 | 設定場所 | 値, 取得元, 設定方法 |
|---|---|---|---|
APP_ENV |
src | GitHub | - ローカル: local- 開発環境: dev- QA環境: qa- 本番環境: prod
|
API_HOST |
src | GitHubActions | 環境毎にAさんに確認 |
GA_MEASUREMENT_ID |
GoogleAnalytics | GitHub | https://analytics.google.com/path/to/取得できるところ |
当たり前ですが実際の値は記事に書けないので、環境変数の内容はだいぶ端折ってます。
このテーブルの行がわーっと増えるイメージです。
ポイント
値の取得方法が自明である
このドキュメントの良さはなんと言っても値の取得方法が自明であることです。
秘匿情報はリンク先のアクセス権限で絞られているはずですし、秘匿しなくていいものはそのまま書いておきます。
聞かないとわからないものは、誰に聞けばわかるかを書きます。
これがあれば新規参入者の環境立ち上げもスムーズに行きます。
また、何かしらの作業で不慮の事故があり環境変数の設定値が吹っ飛んだ(実話)なども復帰が容易です。
環境変数ってだいたい誰かの頭にあるのをDMで聞くとかみんな忘れてて探し回るとかが多いので、じゃあ書いておけばええやんという当たり前の解決方法ですね！
利用箇所・設定箇所を追える
環境変数はコードと違って検索することができません。
なので利用箇所や設定箇所を記載しておくことで、「あれ、この環境変数ってもう消してもいいんだっけ？」みたいなゴミ掃除を安全に行えます。
(もちろんドキュメントをメンテナンスできているという前提ですが)確実にない状態よりは安全に扱えます。
おまけ： .env.example の中身
.env の作成元である .env.example の中身もわかりやすくしておいてほしいです。
私は実際には以下のように設定しています。
# 設定値はドキュメントを参照してね
# See: https://example.com/docs/environments
########################
# Required ↓ 起動に必要
########################
# Environment
APP_ENV="local"
# API Endpoint
API_HOST="https://api.example.com/"
########################
# Optional ↓ 起動に不要
########################
# GA 計測ID
GA_MEASUREMENT_ID=
.env.example ポイント
起動に必要か、不要なのか、それがわかればOKだと思っています。
起動に必要なものは、ないとそもそも起動しないものや、大半の機能が利用できないなどです。
起動に不要なものは、ごく一部の機能が動かないだけや、特定のシーンのみ利用すべきものですね。
たまにしか触らないプロジェクトでも、これさえできていれば環境変数不足で「謎のエラーがでて久々の起動で動かない！」という事故を防げるかなと思います！
あとがき
今までいろんなプロジェクトに関わってきましたが、意外と環境変数の取得方法が明記されていることってなかったなと思い提案してみました。
いいなと思っていただけたら簡単なのでぜひ真似してみてください。
人によってはドキュメントに書き起こすことがセキュリティ的に嫌だと忌避するかもしれませんが、個人的にはどこで誰が持っているかわからない状態より明示的にちゃんと管理できている方が安心感がありますね。
(落とし所は秘匿情報だけは一覧から抜いて、書いてないものは〇〇さんに聞くとしておくとか？)
Discussion