あかぎれが痛い

お腹が痛い人のブログです。Techネタや旅行ネタ中心に書いてます。

数行のメソッドにもリファレンスマニュアルを用意すべき?

こんにちは。

コミケ前の閉塞感をどうにかしたいのでブログを書いています。

f:id:seal2501:20181125234713j:plain

事の発端

先日、ジョインしたばかりの年上のメンバーが作成したPRを、私がレビューした時の話です。 既存コードであるプライベートメソッドの使い方がまずく、正しくない挙動をするコードが含まれていたためそれを指摘したところ「そもそもメソッドのマニュアルやドキュメントがないのが悪い」と言われる体験をしました(ちなみにそのメソッドは5行)。

実際、1. プライベートメソッドに対してドキュメントを用意すべきか、また2. 数行のメソッドにドキュメントが必要なのかということについては考えてもみなかったので、必要性を考えてみました。

パブリックメソッドの場合

基本的には外部に公開している部分なので、リファレンスマニュアルがあっても良いでしょう。 オープンソースではないクローズドなチーム開発の場合は、コード上に書くよりも、別途ドキュメント管理ツールで作成する感じが一般的かなぁ、と思います。そこは企業文化によってまちまちかもしれません。

ユニットテスト単体テスト)をしている場合

個人的には、少人数のチームで開発しているような場合は、リファレンスマニュアルを作成するよりテストコードを見ればいいのでは?と思っています。テストコードで普通にメソッドの使い方がコードで書いてあり、かつ特定の場合の動作が記述されているからです。むしろ、テストコードを見てメソッドの使い方がわからないのであれば、テストに致命的な欠損があるか、テストコードがイケてない状態ではないでしょうか。

プライベートメソッドの場合

ここから本題です。プライベートメソッドの大部分は、リファクタリングにより生じるものかと思います。Railsだと、ControllerのStrong Parametersとかもありえますね。 プライベートメソッドはTDDの原則に倣えばテストコードは不要なので、確かに使い方がわからないケースは生じるかもしれません。なので、privateメソッド禁止!なんていう記事が現れたりするのかなぁ。個人的にはプライベートメソッドは全然OK派です。まぁ、JavaScript書いてるときは注意しないといけませんが(つってもexportしなければいいだけですけどね※ES6の話)

本題に戻ります。まぁ、当たり前なんですが、IDEを使っている場合、リファレンスを書けばサジェストしてくれるんですよね。それを考えると、やっぱりプライベートメソッドにもドキュメントはちゃんと書いたほうがチーム開発するならめっちゃ便利だと思います。

VScodevimのように、サジェストしてくれないようなエディタだったとしても、メソッドを見に来た人向けに、メソッド上部に使い方が書いてあるだけでも、だいぶ意味があるかもしれません。(むしろVScodeでサジェストしてくれるプラグインがあれば教えてください!)

数行のコードしかないメソッドの場合

本題その2です。例えばですが、こんなコードにコメントいりますかね?

def JpEra(str)
  case str.to_i
  when 1
    '明治'
  when 3
    '大正'
  when 5
    '昭和'
  when 7
    '平成'
  when 9
    # TODO: 年号発表されたら修正する
    ''
  else
    ''
  end
end

この数字、意味わかります?答えはこちらです。

労働基準行政システムの新元号対応等に係るアプリケーションプログラム改修業務一式(平成30年度開始)|厚生労働省

この140Pのマニュアルを眺めればわかるんだろうけど、このコードだけでは理解できませんね。やっぱり、行数にかかわらず、リファレンスはあったほうがいい気がしてきました。

結論

  1. プライベートメソッドにもリファレンスを付けておきましょう
  2. そもそも疎結合な処理であれば、パブリックメソッドにしてしまいましょう
  3. リファレンスがない場合はコード読みましょう…
    • リファレンスがない→修正しなくてよいはNG。気づいたらリファレンスを書いてください

ぼやき

今のプロジェクト、全部リファレンスついてないんだよなあぁ(白目)

それでは。