Appifyではコードやコメントを他のメンバーが見てすぐ理解できる ことを非常に重視しています。
詳しくは、21日のアドベントカレンダーで書いたスピードと品質を保ちつつスケールをする開発プラクティス という記事に書いたので、読んでみてください。
上記の記事に出てきたAppifyのセルフレビューシートにも「第三者や将来の自分が読んでも理解できるように実装、コメントを書いた」と言うチェック項目が存在します。
他のメンバーのAppifyではレビューをする際にも、「一読してわからないことは読み解くのではなく質問する」と言うプラクティがあります。一読してわからないコードやコメントは、他のメンバーが見てすぐ理解できる コードやコメントではないからです。
それほど他のメンバーが見てすぐ理解できる ことを重視しているAppifyに入社して1ヶ月ほど経ったのですが、コードやコメントを書く際には「他人が理解できるか?」という視点を常に持つ習慣ができました。(完璧にできているかはまた別の話ですが...)
今回は、「他人が理解できるか?」という視点でAppifyに入ってから特に意識するようになったことを3つを紹介します。
※以下の文章の中で使用するアプリケーションレイヤは、レイヤードアーキテクチャのアプリケーションレイヤのことを指しています。
論理的凝集なコードになっていないか気をつける
まず、論理的凝集とそれを回避した方がよい詳細な理由については、弊社のCTOが書いた以下の資料がわかりやすいので見てみてください。
簡単に説明すると、本来は別々のユースケースだけど、コードが重複する部分が存在するのでDRYを理由に1つの関数にして、ユースケース毎に異なる処理の部分だけ、引数で受け取ったフラグで条件分岐するようなコードです。
論理的凝集な書き方にしてしまうと、1つの関数で複数のユースケースを意識しながら読むことになるので、読み手が理解しにくくなってしまいます。
そのため、特にアプリケーションレイヤのコードを書いている時には、自分の書いているコードが論理的凝集になっていないかと言うことを意識しています。
アプリケーションレイヤを宣言的に実装できるように気をつける
アプリケーションレイヤでは、ドメインやインフラ層で実装したオブジェクトやメソッドを使用して、ユースケースを表現していきます。そのため、アプリケーションレイヤを読めば、そのユースケースの処理の流れが理解できると言う状態にしておきたいです。
アプリケーションレイヤをできるだけ、宣言的に記述することで処理の流れが掴みやすくなります。
アプリケーションレイヤでの宣言的な書き方と、宣言的ではない書き方の例です。
// 宣言的な書き方
// forの具体的な処理はドメインのメソッドに閉じ込めて、
// アプリケーションレイヤでは宣言的にそれを利用する
filteredHoges := hoge.FilterByFoo(foo)
// 宣言的ではない書き方
// アプリケーションレイヤーでfor文を記述してしまう。
filteredHoges := make([]Hoge, 0, len(hoge))
for _, hoge := range hoges {
if hoge.Foo == foo {
filteredHoge = append(filteredHoge, hoge)
}
}特にアプリケーションレイヤを実装している際には、宣言的に記述できているかと言うことを気を付けながら書いています。
コメントで理由を説明する時の粒度に気をつける
Appifyではコードと同じくらいコメントも大切にしています。
コメントを書くときに「~にしているのは、Aであるから 」と理由を書く場合があると思います。この際に Aであるから の部分が粒度が粗すぎて読み手に疑問を残してしまうような書き方になっていてレビューで指摘されることが何回かありました。
実際には Aであるから は更に Bであるから 、Cであるから Dであるからと言うふうに分解できて、初見の読み手にとっては、その分解したところまで記述しないとわからない場合です。
実装している本人からすると、 Aであるから というのは十分理由を説明できているように感じてしまうのでついついやってしまいがちで気をつけたいところです。
自分は、「このコメントの粒度は適切か?更に分解して説明しないとわからないと言うことはないか?」と自問しながらコメントを書くようにしています。
会社全体のアドベントカレンダーはこちら！