昨日の研修は内容のレベル感があまりにも低すぎたため聞いていられなくなり午前中で退席した。このときインベスターZの似たような話が頭に思い浮かんだ。新入生を映画館に連れて行きつまらない映画を1人で見せ、先輩たちは新入生が何分で切り上げてくるかを測るという話だった。損切りを早めにしろという教訓だったと記憶している。今回の研修は人事にわざわざ頼み込んで受けさせて頂いている手前、退席しづらかったがこれも損切りである。
さて、APIの仕様についてドキュメントを利用者に提供する必要があったため午後からはswaggerの利用を検討していた。ドキュメント生成のツールは様々あるが、近年ではswaggerがメジャーである。弊社の他チームでも利用例が散見され、その使い方を真似することは容易に思えた。
個人的にドキュメントについて重視していることが2つある。ソースコードからのドキュメント自動生成機能と変更追従性である。ソースコードからのドキュメント自動生成とは、コードやそのコメントからドキュメントを作ることである。ドキュメントのために特定のファイルを作る必要が無いということを意味している。ソースコードにドキュメントのための情報を含めることの良い点はIDEによる支援が受けやすいことである。これは2つめのポイントである変更追従性にも関わってくる。変更追従性とはソースコードの変更を検知しドキュメントも自動で更新されるというものである。変更を追従しない場合は人が手作業によりドキュメントも変更する必要があり、これはなかなか大変である。
というわけで、swaggerを利用しながら上に述べたポイント2つを兼ね揃えたやり方は無いか調べていたがどうやら無いようであった。最終的に別ファイルで手動管理という、最も避けたかった手法を採用しなければならなくなったが、致し難ないというのが感想である。railsで実装しているため、利用言語はrubyになるが、どうしても動的肩付け言語ではソースコードから読み取れない型の情報がある。それにswaggerに書いておくべきリッチな情報はどんな言語でも読み取れない場合が多く、結局コメントとして書くことになる。そのコメントもIDEによる支援が効かないとなれば別ファイルで管理する場合と比較して変更追従性という点で大差はない。世の中のソフトウェアのドキュメントはどのように作られているのか。今度社内のエンジニアで強い人と面談することがあれば聞いてみたい。
