2017年7月24日に行われた「技術的負債ナイト」（https://speee.connpass.com/event/60381/）の登壇資料です。 プログラミングにおいて、どういうコメントをどういう風に書いていけば良いのか、またどのようなタイミングと考え方で書けば良いのかについて述べていきます。

1. 1Confidential Crowdworks, Inc. All Rights Reserved.
負債返済の下準備
“コメント付与まつり〜準備編〜”
2017年7月24日/技術的負債ナイト
株式会社クラウドワークス エンジニア
安田篤史

2. 2Confidential Crowdworks, Inc. All Rights Reserved.
俺たちの戦いはこれからだ
突然ですが、質問です。
お仕事で触るソースのコメント
1. 必要だと思いますか？
2. 十分に書かれていますか？
3. 役に立ったこと、ありますか？

3. 3Confidential Crowdworks, Inc. All Rights Reserved.
負債返済の下準備
“コメント付与まつり〜準備編〜”
2017年7月24日/技術的負債ナイト
株式会社クラウドワークス エンジニア
安田篤史

4. 4Confidential Crowdworks, Inc. All Rights Reserved.
自己紹介:
ayasuda/やすだあつし
芸歴13年
PHPそこそこ, ruby そこそこ, C++少々,
よくいる器用貧乏な普通のエンジ
ニア

5. 5Confidential Crowdworks, Inc. All Rights Reserved.
クラウドワークスの方から来ました
PR

6. 6Confidential Crowdworks, Inc. All Rights Reserved.
マイナスの生産性(ステップ数換算)で
すが、何か？

7. 7Confidential Crowdworks, Inc. All Rights Reserved.
PR
新機能開発や機能改善
あとリファクタリングとかしてます。

8. 8Confidential Crowdworks, Inc. All Rights Reserved.
「コメント」役に立つん？

9. 9Confidential Crowdworks, Inc. All Rights Reserved.
なぜ、そうなってしまうのか。

10. 10Confidential Crowdworks, Inc. All Rights Reserved.
時を遡ること、開発初期。
そこには超少人数(一人と
か)の開発チームが！

11. 11Confidential Crowdworks, Inc. All Rights Reserved.
フレームワークの流儀に乗ると
コミュニケーションコスト下がるよ！

12. 12Confidential Crowdworks, Inc. All Rights Reserved.
プロダクトが上手くいく
= 会社が大きくなる
= チームも大きくなる
= コードも・・・

13. 13Confidential Crowdworks, Inc. All Rights Reserved.
https://twitter.com/hackerearth/status/589337590408433665

14. 14Confidential Crowdworks, Inc. All Rights Reserved.
理想は、コメントなくても
わかるソースコード
しかし、現実そんなコー
ドって・・・

15. 15Confidential Crowdworks, Inc. All Rights Reserved.
TaxCalculator#calc(amount)
消費税の計算をする

16. 16Confidential Crowdworks, Inc. All Rights Reserved.
TaxCalculator#calc(amount)
源泉徴収税の計算をする
WithhodingTaxCalculator#calc(amount)

17. 17Confidential Crowdworks, Inc. All Rights Reserved.
TaxCalculator#calc(amount)
初見で、これが「消費税」の計算ロジッ
クだとは気づけない
WithhodingTaxCalculator#calc(amount)

18. 18Confidential Crowdworks, Inc. All Rights Reserved.
シェアはお控えください
CENSORED

19. 19Confidential Crowdworks, Inc. All Rights Reserved.
理想は、コメントなくても
わかるソースコード
しかし、現実そんなコー
ドって・・・

20. 20Confidential Crowdworks, Inc. All Rights Reserved.
コメントを書き始める
２つのタイミング！

21. 21Confidential Crowdworks, Inc. All Rights Reserved.
タイミング１：
リファクタとか、調査とかしたそ
の時。
コードを調べながら感じた疑問や
気づきは、そのままコメントにす
べし!!

22. 22Confidential Crowdworks, Inc. All Rights Reserved.
タイミング２：
ちょうど、コードをいじるそのタ
イミング
自分のよく知るコードでも、仕様
の変更をするならそこでコメント
を書く！

23. 23Confidential Crowdworks, Inc. All Rights Reserved.
このタイミングが負債返済のベスト。

24. 24Confidential Crowdworks, Inc. All Rights Reserved.
具体的には、
どんなコメント書けばいいの？？

25. 25Confidential Crowdworks, Inc. All Rights Reserved.
なんでもいい。
マジでなんでもいい。
何もないよりマシだ。
本当に何でもいい。

26. 26Confidential Crowdworks, Inc. All Rights Reserved.
アンチパターンとかはWebやリー
ダブルコードを参照してください。
でも、ゼロよりマシです。

27. 27Confidential Crowdworks, Inc. All Rights Reserved.

28. 28Confidential Crowdworks, Inc. All Rights Reserved.
とはいえ、チームやプロダクトによっ
て最適なコメントは異なる。
なので、とりあえず書いてみて、
いろんな人のレビューを経てチームで
コメントのトンマナを作りましょう。

29. 29Confidential Crowdworks, Inc. All Rights Reserved.
RDoc, TomDoc,
pydoc, etc…
ドキュメント生成ツールも視野に入れ
るとベター

30. 30Confidential Crowdworks, Inc. All Rights Reserved.
ドキュメント生成ツールが入っている
方がベターだし、CI組まれている方が
ベターだけど、コメント自体はツール
入れる前から書き始めた方が良い。
ツールはあくまでも綺麗な文書を生成
するだけで、内容自体は生成しない。

31. 31Confidential Crowdworks, Inc. All Rights Reserved.
コメントのないプログラム
+ そこから生成されたドキュメント
コメントのあるプログラム
+ ドキュメント生成されてない
こっちの方がマシ

32. 32Confidential Crowdworks, Inc. All Rights Reserved.
ドキュメント生成ツールの選定基準
 簡単に導入可能・使用可能か？
 シンプルか？
 柔軟な設定が可能か？
 出力形式は求めているものか？
 拡張性は高いか？ ここが最優先かなぁ

33. 33Confidential Crowdworks, Inc. All Rights Reserved.
ビジネスロ
ジック
実装 コメント
そもそも
これが複雑
なので
これも複雑
ここだけ
シンプル
そもそもビジネスロジックが複雑なのに、
コメントだけシンプルになるわけない

34. 34Confidential Crowdworks, Inc. All Rights Reserved.
Ruby on rails の文書化なら
拡張しやすい yard が
一番いいと思いました。
(個人の見解です)

35. 35Confidential Crowdworks, Inc. All Rights Reserved.
pvande/yard-perl-plugin
Perl のコードを文書化する。
USE AT YOUR OWN RISK とのこと。

36. 36Confidential Crowdworks, Inc. All Rights Reserved.
Custom Handler を定義することで
Ruby の DSL 形式のメソッドにも対応可能

37. 37Confidential Crowdworks, Inc. All Rights Reserved.
p0deje/yard-doctest
コメントの中のサンプルコードを
実際に動かしてテストする

38. 38Confidential Crowdworks, Inc. All Rights Reserved.
lsegal/yard-spec-plugin
RSpec のテストコードを API ドキュ
メント中に含めるプラグイン

39. 39Confidential Crowdworks, Inc. All Rights Reserved.
自作のプラグインも
割と作りやすいです。
(@plantuml プラグイ
ン)

40. 40Confidential Crowdworks, Inc. All Rights Reserved.
PR
「yard の rails 向け拡張方法決定版!!
ぼくのかんがえた
さいつよのどきゅめんと」
近日公開予定！！

41. 41Confidential Crowdworks, Inc. All Rights Reserved.
手法とツールは揃った！
あとは書いていくだけだ！

42. 42Confidential Crowdworks, Inc. All Rights Reserved.
大事なこと。
頑張らない。

43. 43Confidential Crowdworks, Inc. All Rights Reserved.
現実の負債と同じで、一気に返そ
うとすると無理がきます。
ゆっくり、負担のない範囲でコメ
ントをつけていくのがベター。

44. 44Confidential Crowdworks, Inc. All Rights Reserved.
大事なこと。その２。
仲間を増やそう。

45. 45Confidential Crowdworks, Inc. All Rights Reserved.
規模にもよるけど、一人でコメン
トをつけていくのはほぼ不可能。
コメントをつけていく仲間を増や
していきましょう。（ゆっくり）

46. 46Confidential Crowdworks, Inc. All Rights Reserved.
大事なこと。最後。
空気を作ろう。

47. 47Confidential Crowdworks, Inc. All Rights Reserved.
負債返済の下準備
“コメント付与まつり〜準備編〜”
2017年7月24日/技術的負債ナイト
株式会社クラウドワークス エンジニア
安田篤史

48. 48Confidential Crowdworks, Inc. All Rights Reserved.
ご清聴
ありがとうござい
ました。