Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Speaker Deck
PRO
Sign in
Sign up for free
リーダブルなPHPDocを目指して / 20210707-readablelt-nishihara
Rakus_Dev
March 14, 2022
Technology
0
870
リーダブルなPHPDocを目指して / 20210707-readablelt-nishihara
Rakus_Dev
March 14, 2022
Tweet
Share
More Decks by Rakus_Dev
See All by Rakus_Dev
障害対応を自動化した話 / 20220609_Automation
rakus_dev
0
370
横断部門としての取り組み紹介(研究開発、共通基盤開発) / rakus-meetup-202206
rakus_dev
0
360
若手が可読性を上げるために気を付けたこと / 20210707_readablelt_nazato
rakus_dev
0
870
インフラエンジニアとしての成長記 / 20220302_Meetup_maekawa
rakus_dev
0
400
右も左も分からない1年目が上流工程を理解するまでの話 / 20220302-meetup-nagata
rakus_dev
0
410
入社して3年間で『Rundeck』を使って自動化した「面倒」な作業たち / 20220302-meetup-kanamori
rakus_dev
0
480
ラクスUI開発課のチーム活動 / 220222_uiux
rakus_dev
0
490
SaaSマルチヒットメーカーラクスのインフラ戦略 / 20220208_TechCon2022_kanemoto
rakus_dev
1
1.2k
楽楽精算のサービスと共に成長するエンジニア組織の3年間とこれから / 20220208_techcon2022-seisan
rakus_dev
0
1.2k
Other Decks in Technology
See All in Technology
Rethinking how distributed applications are built
tillrohrmann
0
120
拡散確率モデルと音声波形生成
yumakoizumi
1
590
QiitaConference2022
fuwasegu
0
210
サーバレスECにおける Step Functions の使い方 〜ステートマシン全部見せます!〜
miu_crescent
0
200
oakのミドルウェアを書くときの技のらしきもの
toranoana
0
140
FoodTechにおける商流・金流・物流の進化/Evolution of Commercial, Financial, and Logistics in FoodTech
dskst
0
420
わたしを元気づける Botを作ることにした / JAWS-UG 福岡 20220626
eriasano
0
100
Empath Company Deck
empathpr
0
180
Building smarter apps with machine learning, from magic to reality
picardparis
4
3.2k
MRTK3 - DataBinding and Theming 入門
futo23
0
210
ZephyrRTOSのLongan Nanoへの移植
tokitahiroshi
0
110
サイボウズの アジャイル・クオリティ / Agile Quality at Cybozu
cybozuinsideout
PRO
4
2.5k
Featured
See All Featured
Large-scale JavaScript Application Architecture
addyosmani
499
110k
KATA
mclloyd
7
8.7k
Documentation Writing (for coders)
carmenhchung
48
2.6k
Put a Button on it: Removing Barriers to Going Fast.
kastner
56
2.3k
Git: the NoSQL Database
bkeepers
PRO
415
59k
Producing Creativity
orderedlist
PRO
334
37k
Bash Introduction
62gerente
597
210k
Why You Should Never Use an ORM
jnunemaker
PRO
47
7.6k
Designing Dashboards & Data Visualisations in Web Apps
destraynor
224
49k
Faster Mobile Websites
deanohume
294
28k
The World Runs on Bad Software
bkeepers
PRO
57
5.3k
YesSQL, Process and Tooling at Scale
rocio
157
12k
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をメンテしましょう