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

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

Cdf97a1b1b132c56582773c3ba09a3a6?s=47 Rakus_Dev
March 14, 2022
Technology
0
870

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

Cdf97a1b1b132c56582773c3ba09a3a6?s=128

Rakus_Dev

March 14, 2022
Tweet

More Decks by Rakus_Dev

See All by Rakus_Dev
障害対応を自動化した話 / 20220609_Automation
Cdf97a1b1b132c56582773c3ba09a3a6?s=48 rakus_dev
0
370
横断部門としての取り組み紹介（研究開発、共通基盤開発） / rakus-meetup-202206
Cdf97a1b1b132c56582773c3ba09a3a6?s=48 rakus_dev
0
360
若手が可読性を上げるために気を付けたこと / 20210707_readablelt_nazato
Cdf97a1b1b132c56582773c3ba09a3a6?s=48 rakus_dev
0
870
インフラエンジニアとしての成長記 / 20220302_Meetup_maekawa
Cdf97a1b1b132c56582773c3ba09a3a6?s=48 rakus_dev
0
400
右も左も分からない1年目が上流工程を理解するまでの話 / 20220302-meetup-nagata
Cdf97a1b1b132c56582773c3ba09a3a6?s=48 rakus_dev
0
410
入社して3年間で『Rundeck』を使って自動化した「面倒」な作業たち / 20220302-meetup-kanamori
Cdf97a1b1b132c56582773c3ba09a3a6?s=48 rakus_dev
0
480
ラクスUI開発課のチーム活動 / 220222_uiux
Cdf97a1b1b132c56582773c3ba09a3a6?s=48 rakus_dev
0
490
SaaSマルチヒットメーカーラクスのインフラ戦略 / 20220208_TechCon2022_kanemoto
Cdf97a1b1b132c56582773c3ba09a3a6?s=48 rakus_dev
1
1.2k
楽楽精算のサービスと共に成長するエンジニア組織の3年間とこれから / 20220208_techcon2022-seisan
Cdf97a1b1b132c56582773c3ba09a3a6?s=48 rakus_dev
0
1.2k

Other Decks in Technology

See All in Technology
Rethinking how distributed applications are built
08701c3eabe85450809695cf290ef675?s=48 tillrohrmann
0
120
拡散確率モデルと音声波形生成
B8224b243a146b8fd9a2e783fe3eb371?s=48 yumakoizumi
1
590
QiitaConference2022
0684ef0f8b92614508e0c323c3619462?s=48 fuwasegu
0
210
サーバレスECにおける Step Functions の使い方 〜ステートマシン全部見せます！〜
74cec195bfb6cb5165256d88cb7fcf0f?s=48 miu_crescent
0
200
oakのミドルウェアを書くときの技のらしきもの
6ab47a68ee78e84c34731ce12333deff?s=48 toranoana
0
140
FoodTechにおける商流・金流・物流の進化/Evolution of Commercial, Financial, and Logistics in FoodTech
Ff655584d57df8448153fa618cc86db3?s=48 dskst
0
420
わたしを元気づける Botを作ることにした / JAWS-UG 福岡 20220626
E601ca8296c6ed8d1dc7ae0369b4c54a?s=48 eriasano
0
100
Empath Company Deck
8857de8bd0e81ab30358ccad2a1983c4?s=48 empathpr
0
180
Building smarter apps with machine learning, from magic to reality
7e6a435700dda6cdb22105d601f20892?s=48 picardparis
4
3.2k
MRTK3 - DataBinding and Theming 入門
Fccbd625997f63e7b251d9725cb905a5?s=48 futo23
0
210
ZephyrRTOSのLongan Nanoへの移植
0c9a0a8d6b0bb70aab9546484e294be0?s=48 tokitahiroshi
0
110
サイボウズの アジャイル・クオリティ / Agile Quality at Cybozu
A97eee01397705443a72a48ce29d3e19?s=48 cybozuinsideout
PRO
4
2.5k

Featured

See All Featured
Large-scale JavaScript Application Architecture
96270e4c3e5e9806cf7245475c00b275?s=48 addyosmani
499
110k
KATA
E9221b172e78e888355fa2fe4541b595?s=48 mclloyd
7
8.7k
Documentation Writing (for coders)
61857dafbd287b3027c4dcea9008ad3c?s=48 carmenhchung
48
2.6k
Put a Button on it: Removing Barriers to Going Fast.
Bfd6b681ec6e8c9bef82ff0521c364f7?s=48 kastner
56
2.3k
Git: the NoSQL Database
20bfe76b3d6105641f879fe45cfc9272?s=48 bkeepers
PRO
415
59k
Producing Creativity
Ae14cc4491ac334f9cd23f9f93b4305e?s=48 orderedlist
PRO
334
37k
Bash Introduction
812e1705ff0f8bc1bcf18587bde687d5?s=48 62gerente
597
210k
Why You Should Never Use an ORM
88bc30284c6a424b63a92aad27d0ba36?s=48 jnunemaker
PRO
47
7.6k
Designing Dashboards & Data Visualisations in Web Apps
Fde6c3a50ca518a909ef35c22c0ee0e4?s=48 destraynor
224
49k
Faster Mobile Websites
C620790ae5bf5b50c245b2e0ef95f338?s=48 deanohume
294
28k
The World Runs on Bad Software
20bfe76b3d6105641f879fe45cfc9272?s=48 bkeepers
PRO
57
5.3k
YesSQL, Process and Tooling at Scale
D09fad3e36ae6841f54820be0e907f7a?s=48 rocio
157
12k

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