Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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

Rakus_Dev
March 14, 2022

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

Rakus_Dev

March 14, 2022
Tweet

More Decks by Rakus_Dev

Other Decks in Technology

Transcript

  1. #readablelt
    ©2021 RAKUS Co., Ltd.
    リーダブルな
    PHPDocを目指して
    株式会社ラクス
    西原 優人

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  4. #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
    ※テキストで当日の発表内容が紹介されています

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide