リーダブルなPHPDocを目指して / 20210707-readablelt-nishihara

Slide 1

Slide 1 text

Slide 2

Slide 2 text

#readablelt 自己紹介経歴 ● 2015年に新卒でラクスに入社 ● 「Mail Dealer」や「Chat Dealer」の開発を経て現在は「配配メール」の開発担当良く触る技術 ● PHP ● JavaScript ● Node.js ● PostgreSQL 西原　優人 (masato nishihara) Twitter : whiteFox_73 趣味 ● アウトドアフットサル／スノーボード／バイク／ペンギン ● インドア音楽鑑賞／ゲーム／ペンギン

Slide 3

Slide 3 text

#readablelt 配配メールとは ● メールマーケティングに必要な機能を備えたメール配信サービス ● マーケティングオートメーションツールを備えたプランもある ● 現在サービス開始から15年目

Slide 4

Slide 4 text

#readablelt 2月にあったRAKUSMeetUpにて Speaker Deck https://speakerdeck.com/whitefox_73/14nia n-mu-falsesabisutojin-hou-mobu-mutamefal serihuakutaringuzhan-lue logmi Tech https://logmi.jp/tech/articles/323993 ※テキストで当日の発表内容が紹介されています

Slide 5

Slide 5 text

#readablelt 今回の内容はまたリファクタリングの話になります

Slide 6

Slide 6 text

#readablelt 今回の内容はプログラムには影響しないけど重要なコメントPHPDocについてです

Slide 7

Slide 7 text

#readablelt 今回の内容は PHPDocとはPHPで書かれたのクラスや関数などのブロックに記述できるDocComment内に記述する書式

Slide 8

Slide 8 text

#readablelt 今回の内容は実際のイメージ

Slide 9

Slide 9 text

#readablelt 今回の内容は PHPDocの書き方に関しては弊社ブログにもまとめています型を使いこなすためのPHPDocの書き方 https://tech-blog.rakus.co.jp/entry/20210326/php#PHPDo c%E3%81%A8%E3%81%AF 同じチームの後輩が書いてくれました !!

Slide 10

Slide 10 text

#readablelt 今回の内容は無法地帯となっていたPHPDocをメンテしましたって話

Slide 11

Slide 11 text

#readablelt メンテされてないとはどんな状態だった？一つ目

Slide 12

Slide 12 text

#readablelt メンテされてないとはどんな状態だった？書いてない…

Slide 13

Slide 13 text

#readablelt メンテされてないとはどんな状態だった？二つ目

Slide 14

Slide 14 text

#readablelt メンテされてないとはどんな状態だった？フォーマット違う…

Slide 15

Slide 15 text

#readablelt メンテされてないとはどんな状態だった？三つ目

Slide 16

Slide 16 text

#readablelt メンテされてないとはどんな状態だった？型違うやん…

Slide 17

Slide 17 text

#readablelt メンテされてないとはどんな状態だった？ 3つ問題点がありましたが、一番ヤバいのは3つ目 ● PHPDocが書かかれている関数と書かれていない関数が混在 ● PHPDocの書き方が統一されていない ● PHPDocに書かれている内容が正しくない事がある PHPDocは真実と嘘が織り交ざっており、まるで詐欺師状態

Slide 18

Slide 18 text

#readablelt なんでメンテしようと思ったの？ ● チームメンバーの入れ替わりで経験則でカバーできなくなってきた ● 生産性を上げる為に、無駄な時間を使いたくなかった ● 役に立っていないPHPDocが勿体ない

Slide 19

Slide 19 text

#readablelt どうやってメンテした？ 3段階でメンテナンスを実施 ● PHPDocの修正 ○ 過去の誤ったPHPDocをあるべき姿に ● ルール作成 ○ 現在進行形で誤った PHPDocが増えないように ● ルール定着 ○ 未来もPHPDocが綺麗に維持できるように

Slide 20

Slide 20 text

#readablelt どうやってメンテした？ PHPDocの修正 ● PHPDocを書く対象の関数は数千個以上… ● まずは利用頻度の高い共通関数から対応 ● 業務の合間に改善施策として長期的に取り組んで対応

Slide 21

Slide 21 text

#readablelt どうやってメンテした？ルール作成 ● コーディングルールにPHPDocに関する項目を追加 ● ルールをチーム内に展開し、PHPDocの認識を合わせる

Slide 22

Slide 22 text

#readablelt どうやってメンテした？ルール定着 ● ルール定着の為、PHPDocもコードレビュー対象 ● チーム内にも共有しレビューを徹底してもらう

Slide 23

Slide 23 text

#readablelt 効果はあった？ ● コードレビューや調査の際に、PHPDocを信頼できるようになった ● IDEの補完が効くようになった ● IDEで誤った不要な警告がでなくなった

Slide 24

Slide 24 text

#readablelt 取り組んでの所感 ● 無法地帯だったPHPDocをメンテした ● メンテを怠ると正常な状態に戻すのがとても大変 ● 信頼できるPHPDocである事が大切 ● IDEの恩恵も受けることが出来て良いことばかり

Slide 25

Slide 25 text

#readablelt サボらずにPHPDocをメンテしましょう