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
Railsアプリケーションと パフォーマンスチューニング ー 秒間5万リクエストの モバイルオーダーシステムを支える事例 ー Rubyセミナー 大阪
falcon8823
5
1.1k
『自分のデータだけ見せたい!』を叶える──Laravel × Casbin で複雑権限をスッキリ解きほぐす 25 分
akitotsukahara
2
640
20250704_教育事業におけるアジャイルなデータ基盤構築
hanon52_
5
780
AI時代の『改訂新版 良いコード/悪いコードで学ぶ設計入門』 / ai-good-code-bad-code
minodriven
12
3.2k
ペアプロ × 生成AI 現場での実践と課題について / generative-ai-in-pair-programming
codmoninc
1
18k
PostgreSQLのRow Level SecurityをPHPのORMで扱う Eloquent vs Doctrine #phpcon #track2
77web
2
530
Startups on Rails in Past, Present and Future–Irina Nazarova, RailsConf 2025
irinanazarova
0
100
テストから始めるAgentic Coding 〜Claude Codeと共に行うTDD〜 / Agentic Coding starts with testing
rkaga
12
4.4k
Node-RED を(HTTP で)つなげる MCP サーバーを作ってみた
highu
0
120
Python型ヒント完全ガイド 初心者でも分かる、現代的で実践的な使い方
mickey_kubo
1
110
Quand Symfony, ApiPlatform, OpenAI et LangChain s'allient pour exploiter vos PDF : de la théorie à la production…
ahmedbhs123
0
190
PHP 8.4の新機能「プロパティフック」から学ぶオブジェクト指向設計とリスコフの置換原則
kentaroutakeda
2
890
Featured
See All Featured
GraphQLの誤解/rethinking-graphql
sonatard
71
11k
Exploring the Power of Turbo Streams & Action Cable | RailsConf2023
kevinliebholz
34
5.9k
CSS Pre-Processors: Stylus, Less & Sass
bermonpainter
357
30k
Evolution of real-time – Irina Nazarova, EuRuKo, 2024
irinanazarova
8
820
The Straight Up "How To Draw Better" Workshop
denniskardys
234
140k
ReactJS: Keep Simple. Everything can be a component!
pedronauck
667
120k
It's Worth the Effort
3n
185
28k
Principles of Awesome APIs and How to Build Them.
keavy
126
17k
The Art of Delivering Value - GDevCon NA Keynote
reverentgeek
15
1.5k
KATA
mclloyd
30
14k
Why You Should Never Use an ORM
jnunemaker
PRO
58
9.4k
Making the Leap to Tech Lead
cromwellryan
134
9.4k
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