# ミノ駆動本_読書py[12] みんなのメモ ###### tags: `ミノ駆動本` - このメモはWebに公開されています（HackMDチーム） - リンクを知っている人は見られます - HackMDにログインして編集できます ## お願い事項 https://twitter.com/MinoDriven/status/1541334416622256130 > 【お願い】 拙著『良いコード／悪いコードで学ぶ設計入門』に関する情報発信について。 ブログ等で発信の際は、引用の範囲を超え、著作権侵害となる場合は勿論のこと、拙著の詳細内容が分かるような表現での公開はお控え頂けると助かります。 ご感想や拙著に基づく試行錯誤は歓迎です。 #ミノ駆動本 > 拙著引用の際は、Qiitaさんの『著作物を引用する際の注意点』が参考になります。適切な引用のもと、情報発信していただけると嬉しいです。https://help.qiita.com/ja/articles/about-copylight #ミノ駆動本 とのことなので勉強会そのもので詳細内容がわかるような記述はしないように気をつけていきましょう。 ## このメモについて このメモは ミノ駆動本_読書py[12]のメモです https://connpass.com/event/271609 読む範囲：11章 ミノ駆動本のサポートページより、Javaのサンプルコードが見られます。 https://gihyo.jp/book/2022/978-4-297-12783-1/support ## 読書会の流れ * 20:00〜20:30 **自由参加**のもくもく会（個人作業） - 事前に読む時間がとれなかった方はここで読んじゃいましょう（ざっとで大丈夫です） - 合わせて、この**HackMD**に話したいことを各自書いてください - ログインすれば書ける設定にしています - ここがわからん、ここはわかった　お気軽に書き込んでみてください - HackMDの書き込みに投票し、みんなが気になるところをわいわい読み解いていきます * 20:30〜22:00 読書会本編（みんなでわいわい） * Discordでスライド共有して別途案内します * 20時30分開始の本編では、「わたしこれ気になる！」という話題に `:+1:` と書いて投票します。 * :+1: する上限はありません。気になる話題に全部 :+1: しちゃいましょう。ただし1つの話題には1個だけ:+1:でお願いします * 票数が多い話題から話していきます。 ## 以下、もくもく会ワークゾーン ### 感想、気付き - 皆さん、ふだんどれくらいコメント書きますか？ :+1: - 私（nikkie）はほとんど書かないです。doctest含むテストコードと読みやすい命名・設計に時間を使ってます - コードが理解しやすくなるならコメントじゃない手段でもいいよねという考え方 - 私(Yumihiki)はWhyについてはよく書きます - 定数値の値の根拠とか - 傍目から見たら「何これ？」ってなりそうな箇所とか - 逆にいうと何をやっているかは書かないことが多いです（docstringに概要レベルは書く） - 以下は各節で「これってどういうことなんだろう」「ここからこういう気付きがあった」などを書き出すゾーンです。 ### 11章 コメント ―保守と変更の正確性を高める書き方― #### 11.1 退化コメント - わかりみ - https://docs.python.org/ja/3/library/doctest.html - doctestをうまく使えばこういうことは防げるのかなとぼんやり - 挙動をなぞるコメント、DRY原則に反すると言えるような - 『達人プログラマー』のDRY原則の話題の1つです - 『リーダブルコード』にあったのですが、挙動をなぞるのではなく、もう少し上の抽象度でやりたいこと（意図）を書くといいらしいです - → どの程度の抽象度まで書けばいいのかの加減が難しい気がします。基準とまではいかなくても、何かコツのようなものがあるのでしょうか？:+1::+1: #### 11.2 コメントで命名をごまかす - メソッド名とか、どうしようかなって思うんですが - https://qiita.com/baby-degu/items/d058a62f145235a0f007 :+1: - 単一責任の原則とかを意識すれば良いのかしら - メソッド名をシンプルにしよう、みたいなニュアンスで他の章で触れられていた気がするけどお客様の中にご存知の方、いらっしゃいませんか・・・！ - 命名ごまかしは『リファクタリング』のCode Smell（よくないコードの状態）の1つ:+1: - 「コメントを消臭剤として使わない」 - 変数名や関数名を変えよう（『リファクタリング』では変え方も紹介） - 私は「コメントがあった方が読みやすいのでメソッドの前にコメントを書いて欲しいです」って言われた時にこの辺りで書いてあることを伝えて進めたことがあります。:+1: - なのでその時は「もうちょっと分かりやすいメソッド名にしますね」って改善したはず - 命名ごまかしの例で思い出した同様の例 https://youtu.be/kHLYfe-hTTw?t=120 - このLTは面白いです（ただコメント章とは全く関係ないです） - ちょっとどんなのか時間があれば見てみたい:+1: :+1: - #### 11.3 意図や仕様変更時の注意点を読み手に伝えること - この言葉をいつも耳に刻んでいます、がコメントを書くならこういう風に思っているというだけで以下と本章の意図は異なっていそう、すみません。:+1: - https://twitter.com/t_wada/status/904916106153828352 - >コードには How テストコードには What コミットログには Why コードコメントには Why not:+1: を書こうという話をした - 11.3はミノ駆動さんの経験からくるコメントのルールと思われます :+1::+1: - 確かにそうですね、ちょっと書いている内容と違うな・・・ - - #### 11.4 コメントのルール　まとめ - - - #### 11.5 ドキュメントコメント - Pythonだとdocstringで良いのかな。PyCharmでちゃんとチェックはできたはず - https://peps.python.org/pep-0257/ - 2001年に投稿されていてびっくり :+1: - 脱線しちゃうけどドキュメントといえばFastAPI！ - https://fastapi.tiangolo.com/ja/#api - - ドキュメントコメント、全部の関数やクラス・メソッドに書こうではなく、APIとして公開されるものだけでいいという考え方を知りました（『Clean Code』）:+1: - docstringを書かなくても、変数名と型ヒントだけでも、エディタのサポートを受けて書きやすくなりますね（VS Codeの経験から）:+1: 番外編 - https://nikkie-ftnext.hatenablog.com/entry/clean-code-chapter4-comment:+1: - https://nikkie-ftnext.hatenablog.com/entry/readable-code-chapter5-and-6-comment:+1: