過去が分からなくなる前に、ソフトウェア開発の歴史を残そう

2019-12-10雑記

• 「このソースコード、奇妙な構造になっているけど、どうしてこうなっているのだろう？当時を分かる人はもういないから、改修するのが怖いな」
• 「ドキュメントに書かれている内容がよく分からない。知りたいことが書かれていない。誰に聞いたらよいだろうか？」

どうも、ベタオシです。

ソフトウェア開発を続けていると、昔のドキュメントやソースコードに対して「何故、このような姿になっているのか？」という疑問が出てきます。

当時を知る人がいればいいのですが、もういないことが多いです。そのため、きっとこうだろうと自分で解釈して、ドキュメントやソースコードを改修せざるを得ない状況になります。

僕の職場でもこのような状況がしばしば発生します。こんなことにならないように、普段からどういうことに気をつければよいか、僕の考えを紹介します。

この考えは組み込みソフト開発を10年以上続けてきた中で、偉大な先人の知恵や自分の試行錯誤を合わせて出てきたものです。

この記事には次のことを書きました。

• 　ドキュメントやソースコードを、自分以外の人が見た時に、分からないことが少なくなるようにする工夫

何故こうなっているのかを記していく

数字の理由を書く

ドキュメントやソースコードに書いてある数字を選んだ理由を書いていきましょう。現在の自分にとって当たり前、当然の数字であっても、未来の自分や他人には何故この数字になっているのか分かりません。

数字を決めるために使った情報はどこから参照したものなのか？計算して求めたものであれば、どんな式を使ったのか？式はどこから参照されたものなのか？それぞれ理由や根拠を示しておきましょう。後で読み返した時に、同じ結果にたどり着けるだけの情報が残されている状態が理想です。

もし、数字に根拠が無ければ、経験則であることを示しておきましょう。未来の自分や他人には、何らかの意図があって決めたと思ってしまうかもしれません。

背景を書く

公式ドキュメントに書くのは難しいですが、ソースコードに背景事情のメモがあると理解が深まります。

短期間で仕上げる必要があり、あまり深い検討が行われなかったとか、現在の状況は暫定措置であり、最終的な修正が必要で、それを行わなければ、XXXといった問題が出てくるとか。

これだけを見ると、こんな残念なコードがあったというネタになりそうですが、全く情報が無いよりマシです。どこに手を入れなければならないのか、分かりますから。

一年後に見ても分かるように書く

こんなことを書いても仕方ないよなと思うことも示しておきましょう。どれくらいしっかり書いておくべきか？明日、全てを忘れてしまっても大丈夫なように書いてあると心配がありませんね。常にこれを心がけることは難しいですが、どこまでやれば理想状態なのかが分かっているのは重要です。

もう少し具体的な目安として、自分が一年後に読み返しても意味が理解できるようにしておく程度に、文章を書いておくといいと思います。これは僕の経験則から出てきたものなので、もっとよい指針が他にあるかもしれません。今のところ、大切な情報が記されていない、当時の自分が何を考えていたのか分からない、という状況にはなっていません。

全てを示すことはできないと覚悟する

これまで、出来るだけ文章やメモを残しておくように主張してきました。しかし、どれだけ注意して書いておいても、抜け落ちてしまう情報は出てくると思います。

こればかりはどうしようもないと割り切る場合、他人にレビューしてもらう等の対策をする場合、その他の方法を使う場合と様々な方針が考えられるので、状況に応じて手段を選択していけばいいと思います。

何故記していかなければならないのか

人間は簡単に忘れる生き物だから

すでに何度か書きましたが、人間は簡単に忘れてしまう生き物だからです。半日前のことさえ思い出せないことだってたくさんあります。

これを読んでいる方は一週間前の食事を覚えているでしょうか？僕は言えません。

今年最初に書いたソースコード、ドキュメントは何だったか覚えていますか？僕は全く覚えていません。

同じ人間が見ると限らないから

自分が再び担当すると決まっているならドキュメントやソースコードのメモは多少砕けたスタイルで残してもいいかもしれません。

しかし、違う人間が見る可能性もいくからあると思います。その人は新人かもしれません、他部署から移ってきた人かもしれません。もしかしたら、派遣社員かもしれない。そういう人たちが見る可能性を考慮して、書いていく必要がありますね。

記していくと間違いに気づけるから

これは僕がよく経験することです。他人に説明できるように書いていくと、設計ミスに気づくことができます。設計時は誤りに気づかなくても、改めて読み直すことで、1人レビューのような効果がありそうです。

まとめ

ドキュメントやソースコードを、自分以外の人が見た時に、分からないことが少なくなるようにする工夫について紹介しました。

実はソフトウェアの設計内容を示したドキュメントより、何故そのように設計したのかを書く方が大切だったりする

と個人的に考えています。

自分の頭の中を、他人がドキュメントやソースコードから想像するのはとても難しくて、当てることはまず不可能でしょう。それなら、数日経って頭から消えてしまわないうちに、書き出してしまった方がよさそうです。

それではまた、ベタオシでした