Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Features
Speaker Deck
PRO
Sign in
Sign up for free
Search
Search
リーダブルなPHPDocを目指して / Aiming for a readable PHPDoc
Search
Masato Nishihara
July 06, 2021
Technology
0
48
リーダブルなPHPDocを目指して / Aiming for a readable PHPDoc
2021/7/7に開催されたリーダブルコード LT会 - vol.2で発表したスライドです。
Masato Nishihara
July 06, 2021
Tweet
Share
More Decks by Masato Nishihara
See All by Masato Nishihara
ウォーターフォールとアジャイルと楽楽明細/Waterfall×Agile×Rakurakumeisai
whitefox_73
1
840
14年目のサービスと今後も歩むためのリファクタリング戦略
whitefox_73
0
1.7k
正攻法はあるのか!?泥臭く戦ったNode.jsバージョンアップ一部始終
whitefox_73
4
5.9k
Other Decks in Technology
See All in Technology
サラリーマンの小遣いで作るtoCサービス - Cloudflare Workersでスケールする開発戦略
shinaps
2
470
Terraformで構築する セルフサービス型データプラットフォーム / terraform-self-service-data-platform
pei0804
1
200
CDK CLIで使ってたあの機能、CDK Toolkit Libraryではどうやるの?
smt7174
4
190
2025/09/16 仕様駆動開発とAI-DLCが導くAI駆動開発の新フェーズ
masahiro_okamura
0
130
AIがコード書きすぎ問題にはAIで立ち向かえ
jyoshise
1
110
要件定義・デザインフェーズでもAIを活用して、コミュニケーションの密度を高める
kazukihayase
0
120
データ分析エージェント Socrates の育て方
na0
7
2.5k
AI時代を生き抜くエンジニアキャリアの築き方 (AI-Native 時代、エンジニアという道は 「最大の挑戦の場」となる) / Building an Engineering Career to Thrive in the Age of AI (In the AI-Native Era, the Path of Engineering Becomes the Ultimate Arena of Challenge)
jeongjaesoon
0
250
バイブスに「型」を!Kent Beckに学ぶ、AI時代のテスト駆動開発
amixedcolor
2
590
Snowflake Intelligence × Document AIで“使いにくいデータ”を“使えるデータ”に
kevinrobot34
1
120
Firestore → Spanner 移行 を成功させた段階的移行プロセス
athug
1
500
RSCの時代にReactとフレームワークの境界を探る
uhyo
10
3.5k
Featured
See All Featured
Principles of Awesome APIs and How to Build Them.
keavy
126
17k
How to Ace a Technical Interview
jacobian
279
23k
Context Engineering - Making Every Token Count
addyosmani
3
60
Typedesign – Prime Four
hannesfritz
42
2.8k
Done Done
chrislema
185
16k
Building a Scalable Design System with Sketch
lauravandoore
462
33k
The Power of CSS Pseudo Elements
geoffreycrofte
77
6k
Designing Dashboards & Data Visualisations in Web Apps
destraynor
231
53k
The Cost Of JavaScript in 2023
addyosmani
53
8.9k
Balancing Empowerment & Direction
lara
3
620
Helping Users Find Their Own Way: Creating Modern Search Experiences
danielanewman
29
2.9k
Building Adaptive Systems
keathley
43
2.7k
Transcript
#readablelt ©2021 RAKUS Co., Ltd. リーダブルな PHPDocを目指して 株式会社ラクス 西原 優人
#readablelt 自己紹介 経歴 • 2015年に新卒でラクスに入社 • 「Mail Dealer」や「Chat Dealer」の開発を経 て現在は「配配メール」の開発担当
良く触る技術 • PHP • JavaScript • Node.js • PostgreSQL 西原 優人 (masato nishihara) Twitter : whiteFox_73 趣味 • アウトドア フットサル/スノーボード/バイク /ペンギン • インドア 音楽鑑賞/ゲーム/ ペンギン
#readablelt 配配メールとは • メールマーケティングに必要な機能を備えたメール配信サービス • マーケティングオートメーションツールを備えたプランもある • 現在サービス開始から15年目
#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
※テキストで当日の発表内容が紹介されています
#readablelt 今回の内容は またリファクタリングの話になります
#readablelt 今回の内容は プログラムには影響しないけど 重要なコメントPHPDocについてです
#readablelt 今回の内容は PHPDocとはPHPで書かれたのクラスや関数などの ブロックに記述できるDocComment内に記述する書式
#readablelt 今回の内容は 実際のイメージ
#readablelt 今回の内容は PHPDocの書き方に関しては弊社ブログにもまとめています 型を使いこなすためのPHPDocの書き方 https://tech-blog.rakus.co.jp/entry/20210326/php#PHPDo c%E3%81%A8%E3%81%AF 同じチームの後輩が書いてくれました !!
#readablelt 今回の内容は 無法地帯となっていたPHPDocを メンテしましたって話
#readablelt メンテされてないとはどんな状態だった? 一つ目
#readablelt メンテされてないとはどんな状態だった? 書いてない…
#readablelt メンテされてないとはどんな状態だった? 二つ目
#readablelt メンテされてないとはどんな状態だった? フォーマット違 う…
#readablelt メンテされてないとはどんな状態だった? 三つ目
#readablelt メンテされてないとはどんな状態だった? 型違うやん…
#readablelt メンテされてないとはどんな状態だった? 3つ問題点がありましたが、一番ヤバいのは3つ目 • PHPDocが書かかれている関数と書かれていない関数が混在 • PHPDocの書き方が統一されていない • PHPDocに書かれている内容が正しくない事がある PHPDocは真実と嘘が織り交ざっており、まるで詐欺師状態
#readablelt なんでメンテしようと思ったの? • チームメンバーの入れ替わりで経験則でカバーできなくなってきた • 生産性を上げる為に、無駄な時間を使いたくなかった • 役に立っていないPHPDocが勿体ない
#readablelt どうやってメンテした? 3段階でメンテナンスを実施 • PHPDocの修正 ◦ 過去の誤ったPHPDocをあるべき姿に • ルール作成 ◦
現在進行形で誤った PHPDocが増えないように • ルール定着 ◦ 未来もPHPDocが綺麗に維持できるように
#readablelt どうやってメンテした? PHPDocの修正 • PHPDocを書く対象の関数は数千個以上… • まずは利用頻度の高い共通関数から対応 • 業務の合間に改善施策として長期的に取り組んで対応
#readablelt どうやってメンテした? ルール作成 • コーディングルールにPHPDocに関する項目を追加 • ルールをチーム内に展開し、PHPDocの認識を合わせる
#readablelt どうやってメンテした? ルール定着 • ルール定着の為、PHPDocもコードレビュー対象 • チーム内にも共有しレビューを徹底してもらう
#readablelt 効果はあった? • コードレビューや調査の際に、PHPDocを信頼できるようになった • IDEの補完が効くようになった • IDEで誤った不要な警告がでなくなった
#readablelt 取り組んでの所感 • 無法地帯だったPHPDocをメンテした • メンテを怠ると正常な状態に戻すのがとても大変 • 信頼できるPHPDocである事が大切 • IDEの恩恵も受けることが出来て良いことばかり
#readablelt サボらずにPHPDocをメンテしましょう