よこなのへたのよこずき

noteもよろしくね

ソースコードコメント少なめの文化に触れている。しばらく試してみよう

見ているプロジェクト、自分の感覚では結構ソースコードコメントがない(皆無ってわけじゃないけど体感少ない)。前職は金融系ではちゃめちゃに複雑な業務知識が多かったのもあるけど、皆で丁寧にコメントやドキュメントを書きまくる文化があった。クラスやフィールドの説明も全部あったし、メソッドにもどういう理由で何がしたいかとかwikiへのリンクとかが添えられていた記憶がある。

今は

  • コメントを書くより命名やテストでやりたいことを示そう
  • コミットログやGitHubで辿れる履歴を見ながらチームで話そう
  • コメントとソースコードが乖離した場合、コメントがないよりもマズい

などの理由でソースコードコメントがあまりない。少なくとも前の組織に比べると。あ、ちなみにコードとは別に、ドキュメントは積極的に作成する風潮がしっかりある。

私はソースコードコメント書きまくるの肯定派だった(ので上について聞いてみたのだ)けど、話してみると

  • コメント書く派:命名やロジックの工夫でメンテナビリティ保てるのが理想。でも現実的には情報が落ちちゃうからコメントも必要だよね
  • 一方書かない派:コメントがロジックを追従して綺麗に維持できるのが理想。でも現実的には乖離するから命名とかで頑張るしかないよね

ということなのかなと考える。今のところチームは後者寄りのスタンス。

これまで私が書く派全力推しだったのは何故だか考えてみると、「乖離しちゃう」課題は乗り越えられると思っていたからだ。コメントを残す合意さえあれば、遅くともレビューの時点で更新漏れに気付ける。このペインポイントは十分カバーできるし、時間や労力はかかっても多くの人が関わって長くプロジェクトを続けたいなら得られるものの方が大きいという主張を持っていたのだと思う。

この議論についてはTwitterとかでも散々されていると思うんだけど改めて考える機会が来たというお話でしたん。

幸い前述の通りドキュメントはがんがん残そうどんどん共有しようという文化なので、それと合わせてコメントについては上記の方針でやっていくとどんな経験をするか、しばらく試してみることにする。日々、皆と色々相談しながらやっていくよー!