リーダブルコード輪読会 第5章 === # ディスカッションをより豊かにするためのグランドルール - 参加者は毎回任意 - 途中参加・聞くだけでもOK！ - ページ数と同時に、節のタイトルやキーワードを記入してもらえると探す手間を省けて嬉しいです - ファシリテーターや話している人は集中しがちなので、話していない人に議論内容をメモ:pencil:してもらえると嬉しいです - 気になる質問や同感するものには :+1: を末尾につけてください。 - 社外秘情報は書かないこと!!! - オープン設定で誰でも見れてしまうので # タイムテーブル | 時間 | 所要時間 | 内容 |備考 | | -------- | -------- | -------- | -------- | | 15:00 | 5-10分? | (書いてなければ)感想記入&書かれた感想・気づき・疑問をもっと掘り下げたいものを、 :+1: 付けていく | | | 15:10? | 40-45分 | 本の節ごとにディスカッション | | |15:55? | 5分 | 次回読む範囲決めてクローズ | | ## 下に感想などを書いていって下さい。どんな些細なことでもOKです。 --- # 序章、5.1 コメントするべきでは「ない」こと ## 感想・気づき - 参考までにテスト駆動開発の翻訳者の和田さんの方針 - コードコメントは why not - https://twitter.com/t_wada/status/904916106153828352 - やったことはコードで表現できるが、やらなかったことはコメント以外で表現する手段がないためとリプ欄 - :pencil: 上級者向け - コメントはメンテされないことが多いので、個人的にコメントは最小限にする方針が多い:+1: - コメントせずとも分かるように「設計 > 命名 > コメント」の順番で工夫を頑張りたい派 - :pencil: 修正率を顧客にチェックされるプロジェクトでは typo 修正をためらう場合も... - :pencil: 割と気軽にコードを変更できるようになったのはバージョン管理ツールの発達が大きい - コメントを書く/書かないは熟練度が大きく左右するので難しいところ - 読めば分かる内容をわざわざコメントしない > これをどう判断する？という問題に... - :pencil: 書籍等でコメントたくさん書きましょうと書いてある場合があるが、鵜呑みにするとメンテされないコメントの山が。。。 - :pencil: 「すぐに」わかるかは経験によってしまいそう。具体的な線引きは難しそう - 「読めば分かる内容をわざわざコメントしない」は確かにそうだけど。。。 - この本を読んで変数名やメソッド名をわかりやすく付けたきれいなコードなら、確かにコメントは最小限で済むかも ## 疑問 - なし --- # 5.2 自分の考えを記録する ## 感想・気づき - Tチームではwhyを書こうとすると膨らむ傾向があるので、検証内容などは課題チケットのリンクをつけるようにしてる - 管理ツール移行など起きた時の問題があるが... - p.61の単語が漏れる例などは、UnitTestがあればなぜそれをテストしないのかを明示できるので、仕様として把握しやすいと思う - TODOはつけるだけつけて放置されるパターンが多いので、チケット化して紐付けするなど工夫したいところ :+1::+1: - :pencil: TODO: に関連づけたチケットは消化できている？ > 溜まっている。。。 - 経緯や背景（なぜこういう実装をしているのか）をコメントしておくとよいと思う:+1: - 通信先のサービスの制約によるものとか、ライブラリの使い方に癖があるとか、障害でよくない実装をしていたのを修正する時とか - たまになぜこんな実装しているの？と思うようなコードがある　理由がある場合は、コードレビューでコメント追記してと指摘できればよい？ - :pencil: 人の目を増やしつつ、普段から意識する ## 疑問 - なし --- # 5.3 読み手の立場になって考える ## 感想・気づき - 書いている時に読み手の立場=客観視はなかなか難しい...:+1: - ハマって調べたやつは残そうという意識になりやすいが、つまづくことなく書いたものはきっかけがないので難しいところ - なので、最近はPR作る前に全体を眺めるようにして、強制的に客観視するタイミングを用意している - p66. 具体例はクラスの責務の話をしているので、全体像と表現されると違和感 - クラス間連携やフローなどの本当の全体像の話は、コードコメントではなく、クラス図など別なもので管理した方が良いと思うが... - 全体像を把握したい時に、細かい実装の情報はかえってノイズになるのでは？という気もする - :pencil: 全体像をコメントで表現するのは難しそう - :pencil: クラス責務のコメントと混ぜないほうが良いと思った - 要約コメントはユースケースを実現しているクラスにはあると嬉しいことが多い - 全体像、要約コメントは、新メンバーなどコード初見の人にとってはメリットありそう - :pencil: メンテコストがかかるので書かない派 - :pencil: 新メンバ向けにはペアプロ等で口頭で説明するほうがコスパが良さそう ## 疑問 - なし --- # 5.4 ライダーズブロックを乗り越える ## 感想・気づき - 私は設計の不吉な匂いを感知した時も、似たような思考で言語化することが多いですね - とにかく直面した問題を羅列 - 問題が何が起因で起きているのかなど肉付け - 情報の取捨選択を含めてまとめる - 引き継いだコードに「ヤバい、これはhogehoge~」って書かれてたら、オイオイオイ、って思う。。 - 本文にもあるように、なにもないよりはマシか - [ネタだと思いたい](https://www.webcreatorbox.com/webinfo/comments-source-code) ## 疑問 - --- # 5.5 まとめ ## 感想・気づき - コメントは重要だが、闇雲に付ければいいものではない(自戒) - コメントの見直しは重要だが忘れがちorz - [これ](https://qiita.com/hiro-hori/items/1cf28a6ac75db077c8f3)重要 > * きちんと書かれたコードは、それ自体が動作を明確に表す * その場合、コメントは読者にとってノイズにしかならないし、ソースコードを太らせる * だから、ソースコードがドキュメントの役割を果たすような、きれいなコードを書かなければならない * 止むに止まれぬ理由で汚いコードを書いてしまった時に、意図を伝える最後の手段がコメントである > ## 疑問 -