Self-documenting code という言葉をプログラミング関係の文書で最近よく見かけるのですが、日本語でピンとくるような説明が見つからなかったのでメモ。
名称について
- Self-documenting code と呼ばれるのが一般的だが、同じ意味で Self-describing code が使われることもある
- 日本語ではそれぞれ、自己文書化コード、自己記述的コードと訳される (他にも訳語があるかも)
- 対義語は well documented code (ドキュメントが整備されているコード) など
意味
コードコメントやソフトウェアマニュアルといったコード以外のドキュメントを参照しなくても理解できる、「それ自体がドキュメント」のコードのこと。
単に、理解しやすいコードの意味で使われることもあり、人によって解釈が異なる可能性がある。
コードの記述テクニック
Self-documenting code を書くためのテクニックとして、以下のようなものが見つかった。
- マジックナンバーを使わない
- 分かりやすい変数名を付ける
- 細かな関数に分割する
可読性の高いコードを書くテクニックのうち、命名に関するものと共通しているようだ。インデントの使い方や構文などに言及しているサイトは見つからなかった。
批判
どれほど分かりやすくコードを書いたところで、完全な Self-documenting code を作ることはできない。コードを読めばどのような処理が行われるかは分かるだろうが、そのコードが書かれた目的や、その実装方法が選ばれた理由は、コメントやドキュメントがなければ分からない。
