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
54
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
Amazon S3 Filesについて
Avatar for Yuuki Yamashita yama3133
2
210
AgentCore×VPCでの設計パターンn選と勘所
Avatar for Har1101 har1101
3
280
#jawsugyokohama 100 LT11, "My AWS Journey 2011-2026 - kwntravel"
Avatar for Shinichiro Kawano shinichirokawano
0
350
エージェントスキルを作って自分のインプットに役立てよう
Avatar for Yuta Matsumura tsubakimoto_s
0
380
これからの「データマネジメント」の話をしよう
Avatar for SansanTech sansantech
PRO
0
110
プラットフォームエンジニアリングの実践 - AWS コンテナサービスで構築する社内プラットフォーム / AWS Containers Platform Meetup #1
Avatar for Masatoshi Hayashi literalice
1
200
自分のハンドルは自分で握れ！ ― 自分のケイパビリティを増やし、メンバーのケイパビリティ獲得を支援する ― / Take the wheel yourself
Avatar for TAKAKING22 takaking22
1
920
国内外の生成AIセキュリティの最新動向 & AIガードレール製品「chakoshi」のご紹介 / Latest Trends in Generative AI Security (Domestic & International) & Introduction to AI Guardrail Product "chakoshi"
Avatar for NTT docomo Business nttcom
3
1.2k
生成AIが変える SaaS の競争原理と弁護士ドットコムのプロダクト戦略
Avatar for 弁護士ドットコム bengo4com
1
1k
AzureのIaC管理からログ調査まで、​随所に役立つ​SkillsとCustom-Instructions​ / Boosting IaC and Log Analysis with Skills
Avatar for AEON aeonpeople
0
240
はじめての MagicPod生成AI機能 機能紹介から活用方法まで
Avatar for MagicPod magicpod
0
100
Practical TypeProf: Lessons from Analyzing Optcarrot
Avatar for Yusuke Endoh mame
0
370

Featured

See All Featured
The innovator’s Mindset - 
Leading Through an Era of Exponential Change - McGill University 2025
Avatar for Jean-Marc De Jonghe jdejongh
PRO
1
160
Easily Structure & Communicate Ideas using Wireframe
Avatar for Afnizar Nur Ghifari afnizarnur
194
17k
StorybookのUI Testing Handbookを読んだ
Avatar for Shingo Yamazaki zakiyama
31
6.7k
AI in Enterprises - Java and Open Source to the Rescue
Avatar for ivargrimstad ivargrimstad
0
1.2k
How to Build an AI Search Optimization Roadmap - Criteria and Steps to Take #SEOIRL
Avatar for Aleyda Solis aleyda
1
2k
The Impact of AI in SEO - AI Overviews June 2024 Edition
Avatar for Aleyda Solis aleyda
5
800
Documentation Writing (for coders)
Avatar for Carmen Chung carmenintech
77
5.3k
Exploring the Power of Turbo Streams & Action Cable | RailsConf2023
Avatar for Kevin Liebholz kevinliebholz
37
6.4k
Refactoring Trust on Your Teams (GOTO; Chicago 2020)
Avatar for Rebecca Miller-Webster rmw
35
3.4k
So, you think you're a good person
Avatar for Per Axbom axbom
PRO
2
2k
Avoiding the “Bad Training, Faster” Trap in the Age of AI
Avatar for Mike Taylor tmiket
0
130
KATA
Avatar for Megan Lloyd mclloyd
PRO
35
15k

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をメンテしましょう