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
誰のためのコメント? / comments-for-whom
Search
yuki
January 09, 2025
Programming
0
88
誰のためのコメント? / comments-for-whom
【ペチオブ】2025年 新年会 書き初め LT
というイベントで発表したスライドです。
https://phper-oop.connpass.com/event/339339/
yuki
January 09, 2025
Tweet
Share
More Decks by yuki
See All by yuki
今年の抱負 2024/Aspirations for 2024
yyykms123
0
170
Vercel Ship まとめ「2023/5/1-5」
yyykms123
0
150
プロジェクト管理で失敗したこと
yyykms123
0
43
脱初心者のための GitHub Actions
yyykms123
0
310
プロジェクトをリリースするまでのプロセス
yyykms123
0
42
実務で使えるGitコマンド
yyykms123
4
1.1k
過去の自分へ送るLT!
yyykms123
0
86
Other Decks in Programming
See All in Programming
データの民主化を支える、透明性のあるデータ利活用への挑戦 2025-06-25 Database Engineering Meetup#7
y_ken
0
360
Team operations that are not burdened by SRE
kazatohiei
1
310
なぜ「共通化」を考え、失敗を繰り返すのか
rinchoku
1
650
PostgreSQLのRow Level SecurityをPHPのORMで扱う Eloquent vs Doctrine #phpcon #track2
77web
2
530
10 Costly Database Performance Mistakes (And How To Fix Them)
andyatkinson
0
330
Google Agent Development Kit でLINE Botを作ってみた
ymd65536
2
250
VS Code Update for GitHub Copilot
74th
2
640
Flutterで備える!Accessibility Nutrition Labels完全ガイド
yuukiw00w
0
160
「Cursor/Devin全社導入の理想と現実」のその後
saitoryc
0
820
ソフトウェア品質を数字で捉える技術。事業成長を支えるシステム品質の マネジメント
takuya542
1
13k
XP, Testing and ninja testing
m_seki
3
240
すべてのコンテキストを、 ユーザー価値に変える
applism118
3
1.3k
Featured
See All Featured
We Have a Design System, Now What?
morganepeng
53
7.7k
YesSQL, Process and Tooling at Scale
rocio
173
14k
Building Applications with DynamoDB
mza
95
6.5k
Designing for Performance
lara
610
69k
Automating Front-end Workflow
addyosmani
1370
200k
Templates, Plugins, & Blocks: Oh My! Creating the theme that thinks of everything
marktimemedia
31
2.4k
What's in a price? How to price your products and services
michaelherold
246
12k
Imperfection Machines: The Place of Print at Facebook
scottboms
267
13k
Facilitating Awesome Meetings
lara
54
6.4k
Sharpening the Axe: The Primacy of Toolmaking
bcantrill
44
2.4k
Making the Leap to Tech Lead
cromwellryan
134
9.4k
[RailsConf 2023 Opening Keynote] The Magic of Rails
eileencodes
29
9.6k
Transcript
誰のためのコメント? 【ペチオブ】2025年 新年会 書き初めLT 2025.01.09 / Yukimasa Ikeda
目次 1. コメントがないコード 2. 過剰なコメント 3. 意図が伝わらないコメント 4. 理想のコメント 2
1. コメントがないコード function a() { execute(); } 「何をする関数か全く分からない…」 このコードを書いた本人に3年後に聞いても「たぶん緊急対応だった」と返される かも。
コメントがないコードの問題 チームで開発している場合、他のメンバーがコードの意図を理解できない。 自分自身でも時間が経つと記憶が曖昧になる。 3
2. 過剰なコメント 実況中継のようなコメントは、逆にノイズになります。 // ループ処理を開始します for (let i = 0;
i < items.length; i++) { process(items[i]); } 「見れば分かる!」と思わずツッコミたくなる。 コメントを書くこと自体が目的になっているケース。 過剰なコメントの問題 コードが変わってもコメントが更新されず矛盾が生じる。 コメントが増えるほど、意図を探すのが困難になる。 4
3. 意図が伝わらないコメント よくある例: 「TODO: 後で直す」 // TODO: 後で直す const result
= doSomething(); なぜ後で直す必要があるのか? どんな状況を想定しているのか? 意図が伝わらないコメントの問題 他人や未来の自分が見ても、何をしたかったのか分からない。 修正のタイミングや優先度が曖昧になる。 5
4. 理想のコメント コメントを書く際は、以下のポイントを押さえるべきです。 1. 目的を説明する: 「この処理が必要な理由は何か?」を明確にする。 2. 意図を明確にする: 「この方法を選んだ背景は何か?」を伝える。 3.
背景を書く: 設計のトレードオフや、特定の仕様に対応した経緯などを補足する。 理想のコメントの例 // ユーザー一覧を取得する際にページネーションを行うため // クエリにlimitとoffsetを追加しています const users = fetchUsers({ limit: 10, offset: 20 }); 6
まとめ コメントは未来の自分や他人に向けて書く。 ただし、コード自体が意図を伝えられるなら、不要なコメントは書かない。 コメントの量より、質が重要。 7
書き初め 8