むっきゃーストーリー
(アプリで予期せぬ動きがありましたー)
ふむ、このコンフィグが影響してるっぽいな。
sea.land.limit = 10
うーむー...
どういうことなんだろう？コメント欲しいなぁ...
# SeaやLandに行く回数制限 sea.land.limit = 10
まあそうなんだろうけど、そういうのじゃなくて...
なんで回数制限する必要あるの？
なんで10なの？気軽に変えてもいいの？
# さあ... sea.land.limit = 10
むっきゃー
設定ファイルは無言
プログラムと違って、設定ファイルは前後関係でなんとなくニュアンスを理解するとか、そういうのしづらいものです。
そのコンフィグのオフィシャルドキュメントを読んでコンフィグ自体の意味はわかりますが、「なぜ、このアプリで使ってるのか？」はなかなかわかりません。それはアプリのロジックですから。
ツールじゃなくてアプリ内で定義したコンフィグだとしても、「コードからコードを追う」のに比べれば「設定ファイルからコードを追う」のは少々手間です。(まあ追いますけど...追ってコードも無言で何にもわからんってこともしばしば＞＜)
設定値はなおさら無言
10という設定値は、さらに何もしゃべってくれません。
o 10で確定？まだ調整した方がいい？
o 永遠に10でいい？気軽に増やしていい？
本当はアプリで変更した方が良い場面だったとしても、後の人はこう思ってなかなかできないんですよね。
「実はとある処理が10に依存してるとか...値を変えて落ちたらどうしよう（＞＜」
だから...
その値に対する今後のメンテナンス時の判断材料を知りたい
のです。
だから背景コメントを
そんなたいそうなコメントが欲しいわけではないです。ちょこっと...
# お金ないから少なめに sea.land.limit = 10
「じゃあ、お金が入ったら多くして良いわけだ。状況によっては回数制限という機能自体も無くしてもいいのかもしれない。よし判断できる、コメント書いてくださった方に感謝！」
こういう風に、気持ちよく設定ファイルを読みたいものですね。
ゾンビコンフィグ
ありませんか？なんか使われてるかどうかわからないコンフィグがずっと...変更したり削除したりすると何が起こるかわからないからそのままにしてるみたいな。
よくよく分析してみると、もうとっくの昔に不要だったコンフィグだったり、値を変えた方が良かったりってのが判明するとか。
# 特定のショーを観るためだけにインしたときに必要 super.long.wait = true
「じゃあ、普通の遊び方をするときは関係ないコンフィグなんだな。...あれ？特定インの機能って別のシステムに移行されなかったっけ？このシステムではこのコンフィグもう使われてないはず！？」
設定ファイルが読むの楽しいって思えるようになってきませんか？
ゾンビライブラリ
ありませんか？なんか使われてるかどうかわからない依存ライブラリがずっと残ってるとか。メインではなくピンポイントの機能だけで入れた依存ライブラリとかよくありますよね。
よくよく分析してみると、そして、そのピンポイントで入れた機能も実はもう使われていない、もしくは、代替手段ができてもう使う必要がなくなったとか、そうなってたとしてもわからないし気付けないってなりがちです。
compile "sugoi:tokushu-lib:1.0.0" // piari機能で入れた
「そのpiariという機能は...それ自体だいぶ前に使われてないじゃん。追加で外のところでも使ってないようだし外しても大丈夫そうだな(もちろん最終確認はするけど)」
設定ファイルに住みたい！って思えるようになってきませんか？
もちろん全部じゃなくいいので
必須のコンフィグでもう明らかなものもあるでしょう。確かにそういうのは別に何もコメント無くても問題ないです。
コメントが欲しいコンフィグは...例えばこういうのでしょうか:
o 普段と違う値を設定したコンフィグ
o 特定の目的があって設定してるコンフィグ
o マニアックなコンフィグ
まあ、とにかく
「他の人、見てもわかんないだろうな...」
ってコンフィグにコメントを付けたいというところですね。
それはソースコードのコメントとまったく同じです。ソースコードにはコメント書くのに、設定ファイルにコメントを書かない理由はないです。
形式とか気にしなくていい
設定ファイルは、あまりこういう形でコメントを付けるとか慣習があまり決まってないと思います。だから形は気にしないでいいでしょう。
みんながしっかり書くようになって、表現のズレとかがノイズになるくらいになったら「形式どうしよう？」って悩み始めるくらいでいいかと。
それよりまず「伝えること」が先決！
コンフィグはシステムの遺伝子
設定ファイルでフレームワークもツールもアプリも大きく振る舞いを変えます。
それだけ影響力の強いものですから、設定ファイルが読みやすければシステムの全体像を掴むきっかけにもなるかもしれません！
ぜひ、Readable Settings を目指しましょう。
...
...
...
番外、チケットのURL貼ったり
こういうのもアリです。そのコンフィグに関するチケットのURLを貼っとおくとか。
# http://...(略)/MAIHAMA-123 sea.land.limit = 10
チケット見れば、そのコンフィグのこと、使ってる理由、設定した値の妥当性、みんなわかるかもしれません。
git履歴を見れば辿れるかもしれませんが、コミットコメントやコミット粒度にクオリティに依存しますし、コンフィグをまじまじと見てるということは何か急ぎで調べてるってことですから手間なくパッとわかりたいものです。(ちなみにgit履歴がないときもあります。設定ファイルって他のプロジェクト間でコピペされやすいものなので Initial commit でまるごと入ってたり...＞＜)
なので、「日本語が思い付かないなー」ってなったら、もうこれでも良いです。jfluteの身の回りの現場ではよくやってます。(その代わり、チケットにはちゃんと議論を残すように)
まあ欲を言えばチケットのタイトルくらい入ってると嬉しいですけどね。パッと見で何のことなのか知れれば（＾＾
# SeaLand制限機能の実装: http://...(略)/MAIHAMA-123 sea.land.limit = 10
...
...
...
番外の番外、これはダメですよー。
(ダメパターン) # SeaやLandに行く回数制限を10にしている sea.land.limit = 10
