[WIP] 自走プログラマー ~Pythonの先輩が教えるプロジェクト開発のベストプラクティス~

[zerebom]

ソフトウェア開発・実務に寄ったEffective Pythonみたいな本。 https://amzn.to/33FoUxu

Chpter1 コード実装

関数設計

• 関数名
  • 処理内容が想像できる名前にする
  • スコープの小さい単語を使う
  • 戻り値も関数名から想像できるものを返す is_valid()-> Boolなど
• 副作用のない関数にまとめる
• リストや辞書をデフォルト引数にしない
  • 呼び出しごとに初期化されないので冪等性ない
• コレクションを引数にせず、int/strを受け取る
  • 再利用性・ユニットテスト時のデータの用意が簡単になる
• index番号に意味を持たせない
  • 可読性が低い/変更に弱い
  • 辞書/クラスを使おう
• コメントには「なぜ」を書く
  • 基本的に仕様はコードから見て取れるようにする
  • 直感的でない処理にはなぜそうしたかを書く

クラス設計

• 複数の関数で利用するデータ群は辞書でなくクラスで定義する

  メリット

  • デバッグ時にクラス名が表示される
  • IDEの定義元にジャンプできる
  • コード検索しやすい
  • isinstance,型アノテーションができる

    デメリット

  • import,インスタンス化などが面倒

• 引数が多いクラスはdataclassを使う

  Before

  def User:
      def __init__(self, username, email...):
          self.username = username
          self.email = email
          ...

  after

  from dataclasses import dataclass
  @dataclass
  class User:
  username:str
  email:str
  ...

• 別メソッドに値を渡すためだけに属性を設定しない
  言い換えると、あるメソッドを呼び出す前に必ず呼び出すメソッドを作るなど、依存関係がある状態に設計しない。
  @propertyを使うべき

  property

  • propertyとは
    オブジェクトが持っているデータそのもの

  propertyは外部からアクセスする可能性を排除した値で、
  外部から参照、変更するにはgetter,setterからアクセスする必要がある。
  別のメソッドで参照し、呼び出すことも可能。

• インスタンスを作る関数をクラスメソッドにする

  
  @dataclass
  class Product:
  id: int
  name: str
  
  @classmethod
  def retrieve(cld,id)->Product:
      data = hoge(id)
      return cls(data['id'],data['name'])

このようにすると、
```python
from models import Product
product = Product.retrieve(1)

で簡単に値を持ったclsをimportできる
classmethodの説明

モジュール設計

• utils.pyのような汎用的な名前は避ける データ、ビジネス上の仕様に依存しないもののみ格納する

• ビジネスロジックをモジュールに分割する

ユニットテスト

• テストに対象と同等の実装を書かない A = Aとなって、必ず通るテストになってしまう 入力と予測される出力値を用意して対象が出力値を正しく吐くかをテストする

• 一つのテストメソッドで1つの項目のみ確認する 文字列が0以上100以下のときのみTrueを返す関数をテストするなら、

  • 正しいとき
  • 短すぎるとき
  • 長過ぎるとき と分割してテストする。

• テストケースは準備、実行、検証に分割する

• ユニットテストをする観点から設計を洗練させる ユニットテストしやすいコードは良いコード

  • csvの中身を確認するコードなら、各行を表すクラスを分離して、以下のようにテストを書く
    • 各行に対するクラスに対するテスト
    • 結合したときの挙動を見るテストを書く。
  • 関数の引数に必要以上に複雑な値を必要としない
  • 処理を分離してすべての動作確認にすべてのデータが必要ないようにする
  • クラス、関数を分離して、細かいテストは分離した関数、クラスを対象に行う
    　良いコードはテスト時にデータの準備が簡単にできるので、書き直しもラク。

• テストから外部環境の依存を排除しよう 外部リンクにアクセスする処理などは、responsesクラスなどでモックを使って用意する DoS攻撃の可能性、外部リンクの変更によるエラー、アクセスによる処理時間の増加などを抑えられる。

• テスト用データはテスト後に削除しよう ストレージに余計なデータを残さないようにする。
  tempfileモジュールで用意できる

• テストケースごとにテストデータを用意する テストデータを複数テストで使い回すと思わぬエラーがでるので避ける

• テストで確認する内容に関係するデータのみを製作する 何をテストしているかひと目で分かるようにする。
  その他のデータはデフォルトにする

• 必要十分なテストデータを用意する 1万データを超えたら処理を変える関数のテストをする場合は、
  1万という値を引数によって変更できるようにして、処理を軽くする。

• テストの実行順序に依存しないテストを書く。 　それぞれのテストは独立してるようにする。

• 戻り値がリストのテストは要素数もテストする

実装の進め方

• 公式ドキュメントを読む

  • 概して時間がかかるので、予め時間を制限して置く
  • Dashなどドキュメントブラウザーを使う
  • キーワードを使って読むべきとこを絞る

• 1度に実装する範囲を小さくする

  • 出戻りが減る
  • コミュニケーションの誤差が小さくなる
  • 知識の整理にも役立つ

• 基本的な機能だけ実装してレビューする

• 実装方針も相談する

• 開発アーキテクチャドキュメントを用意する

レビュー

• PRの差分にレビュアー向けの説明を書く

  1. 実装の根拠を書く
  2. 仕様や設計をまとめる
  3. コードを改善する
  4. 差分の説明をする
  5. PRの本文に、目的・仕様をまとめたリンク・確認してほしいことを書く
  6. 差分コメントを恒久的な情報に移す

• PRに不要な差分を持たせないようにする

  • PRの目的は一つに絞る
  • PRの粒度は小さくする
  • レビュアのコストが小さくなるように依頼する
  • 差分を見たらすぐにレビューできる状態にしておく

• レビュアはレビューの根拠を明示する

モデル設計

エラー設計

システム設計

やることの明確化

• いきなり作り始めてはいけない
  作る前にイメージを書き出して整理する必要がある。なぜなら、

  • 出戻りを防ぐ
  • 目的を明確にし、作り始めたあと迷子になるのを防ぐ
  • 作業を見積もり、コストを抑えて最大の成果をえるため そのためには以下の流れで作業を行うことが必要
  • イメージや用語、価値を書き出す
  • システム構成やモデルなど大局的な設計をする
  • プログラムを設計
  • プログラムを作る
  • テスト、レビューする
    上記のことをやるためにはエディタを開かないことが肝要

• 作りたい価値から考える

  • どんな痛みを解決するか
  • 痛みの大きさや頻度は
  • 誰の要望、痛みか などを考え、本当に自分が解決するべき課題かを考える

• 100％の要件定義を目指さない
  仕様をきめるとき、はじめから良い答えを求めすぎると失敗しやすい。
  そのため、要件の確度を意識、明記しながら書く必要がある。
  要件定義ドキュメントに作業要件の確度も同時に書くと良い。

画面モックを作る

• 文字だけで伝えず、画像や画面で伝える

• モックアップは完成させる
  作り込みすぎる必要はないが、システム設計に必要な部分は作成する

  • 画面のどこから遷移するか
  • どこに遷移できるから
  • ブラウザ、アプリ全体の枠を書く
  • どういった条件でコンテンツを表示するか

• 遷移、入力、表示に注目する

• コアになる画面から書く

• モックアップから実装までをイメージする

  • どのようなデータ(テーブル、モデル)が必要か
  • キャッシュや集計する処理が必要か

• 最小で実用できる部分から作る リーンスタートアップ参照

• ストーリーが満たせるかレビューをする

  • Webサービスとして価値が提供できるか
  • 使う人のストーリーを実現する遷移、ボタンが揃っているか
  • 触った瞬間に求めていた価値を感じられるか
  • 使う人が使いやすいか、使いこなせるか
  • どういった流れで使い手は使い方を会得するのか