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

リーダブルなPHPDocを目指して / Aiming for a readable PHPDoc

Sponsored · Ship Features Fearlessly Turn features on and off without deploys. Used by thousands of Ruby developers. →
Avatar for Masato Nishihara Masato Nishihara
July 06, 2021
Technology
55
0

リーダブルなPHPDocを目指して / Aiming for a readable PHPDoc

2021/7/7に開催されたリーダブルコード LT会 - vol.2で発表したスライドです。

Avatar for Masato Nishihara

Masato Nishihara

July 06, 2021

More Decks by Masato Nishihara

See All by Masato Nishihara
ウォーターフォールとアジャイルと楽楽明細/Waterfall×Agile×Rakurakumeisai
Avatar for Masato Nishihara whitefox_73
1
890
14年目のサービスと今後も歩むためのリファクタリング戦略
Avatar for Masato Nishihara whitefox_73
0
1.8k
正攻法はあるのか!?泥臭く戦ったNode.jsバージョンアップ一部始終
Avatar for Masato Nishihara whitefox_73
4
6.2k

Other Decks in Technology

See All in Technology
CyberAgent YJC Connect
Avatar for shimayuu shimaf4979
1
180
AI時代に越境し、 組織を変えるQAスキルの正体 / QA Skills for Transforming an Organization
Avatar for miisan mii3king
5
4.4k
オライリーイベント登壇資料「鉄リサイクル・産廃業界におけるAI技術実応用のカタチ」
Avatar for Takumi Karasawa takarasawa_
0
400
AI時代に、 データアナリストがデータエンジニアに異動して
Avatar for jackojacko_ jackojacko_
0
850
Sociotechnical Architecture Reviews: Understanding Teams, not just Artefacts
Avatar for Eberhard Wolff ewolff
1
170
AWSアップデートから考える継続的な運用改善
Avatar for Toru_Kubota toru_kubota
2
110
全社統制を維持しながら現場負担をどう減らすか〜プラットフォームチームとセキュリティチームで進めたSecurity Hub活用によるAWS統制の見直し〜/secjaws-security-hub-custom-insights
Avatar for みずほリサーチ&テクノロジーズ株式会社 先端技術研究部 mhrtech
1
500
Tachikawa.any 運営挨拶
Avatar for daitasu daitasu
0
170
Gaussian Splattingの表現力を拡張する — 高周波再構成とインタラクションへのアプローチ —
Avatar for GPU UNITE gpuunite_official
0
170
RedmineをAIで効率的に使う検証
Avatar for Takayuki Yoshioka yoshiokacb
0
100
LookerとADKで作る社内AIエージェント
Avatar for chanyou0311 chanyou0311
0
200
20260515 ⾃分のアカウントとプライバシーを守る認証と認可の話〜利⽤者向け〜
Avatar for OpenID Foundation Japan oidfj
0
440

Featured

See All Featured
職位にかかわらず全員がリーダーシップを発揮するチーム作り / Building a team where everyone can demonstrate leadership regardless of position
Avatar for MADOX madoxten
62
54k
Practical Tips for Bootstrapping Information Extraction Pipelines
Avatar for Matthew Honnibal honnibal
25
1.9k
Agile that works and the tools we love
Avatar for Rasmus Luckow-Nielsen rasmusluckow
331
21k
How to optimise 3,500 product descriptions for ecommerce in one day using ChatGPT
Avatar for Katarina Dahlin katarinadahlin
PRO
1
3.6k
State of Search Keynote: SEO is Dead Long Live SEO
Avatar for Ryan Jones ryanjones
0
190
Discover your Explorer Soul
Avatar for Emna emna__ayadi
2
1.1k
Have SEOs Ruined the Internet? - User Awareness of SEO in 2025
Avatar for Akash Hashmi akashhashmi
0
340
The innovator’s Mindset - 
Leading Through an Era of Exponential Change - McGill University 2025
Avatar for Jean-Marc De Jonghe jdejongh
PRO
1
170
Code Review Best Practice
Avatar for Trisha Gee trishagee
74
20k
Exploring anti-patterns in Rails
Avatar for Elle Meredith aemeredith
3
350
CoffeeScript is Beautiful & I Never Want to Write Plain JavaScript Again
Avatar for Sam Stephenson sstephenson
162
16k
How To Speak Unicorn (iThemes Webinar)
Avatar for Michelle Schulp Hunt marktimemedia
1
460

Transcript

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

  2. #readablelt 自己紹介 経歴 • 2015年に新卒でラクスに入社 • 「Mail Dealer」や「Chat Dealer」の開発を経 て現在は「配配メール」の開発担当

    良く触る技術 • PHP • JavaScript • Node.js • PostgreSQL 西原　優人 (masato nishihara) Twitter : whiteFox_73 趣味 • アウトドア フットサル／スノーボード／バイク ／ペンギン • インドア 音楽鑑賞／ゲーム／ ペンギン

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

  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

    ※テキストで当日の発表内容が紹介されています

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  19. #readablelt どうやってメンテした？ 3段階でメンテナンスを実施 • PHPDocの修正 ◦ 過去の誤ったPHPDocをあるべき姿に • ルール作成 ◦

    現在進行形で誤った PHPDocが増えないように • ルール定着 ◦ 未来もPHPDocが綺麗に維持できるように

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

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

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

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

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

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